@spboucher/spmail-mcp — SP Mail for AI agents (MCP server)
A Model Context Protocol server that lets an AI agent (Claude Code, Claude Desktop, any MCP client) read, search, draft and send e-mail through the SP Mail REST API.
- stdio transport, one self-contained file:
node dist/index.js. - Same permissions as the REST API, by construction: the server holds only an API key and calls
https://mail.spboucher.ai/api/v1. Scopes, address allowlist, rate and daily limits and the external-send policy are enforced by the API on every call; the server adds no privilege and has no other access (no database, no mail-server credentials, no file system writes). - Prompt-injection hygiene: mail content is returned as delimited untrusted data, never as instructions (see Security model).
- Human approval for external sends is enforced server-side by the key's
external_send_policy(defaultapproval).
Build
cd packages/sdk-ts && pnpm install --ignore-workspace # the MCP server bundles the TypeScript SDK from ../sdk-ts
cd ../mcp && pnpm install --ignore-workspace && pnpm build # → dist/index.js (single file, runs standalone)Configuration
| Variable | |
|---|---|
SPMAIL_API_KEY |
required — spm_<prefix>_<secret>, created by an administrator in SP Mail (Administration → API keys) or with cli key-create |
SPMAIL_BASE_URL |
optional — default https://mail.spboucher.ai |
SPMAIL_MCP_READONLY |
optional — 1 registers only the read tools, whatever the key allows |
At startup the server calls GET /me. A refused key (401) stops the server with a message on stderr. If the API is unreachable, the server starts with every tool and each call is still checked by the API. The key is never printed (stdout carries the protocol, stderr the diagnostics) and never appears in a tool result.
Claude Code
claude mcp add spmail \
--env SPMAIL_API_KEY=spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
-- node /absolute/path/to/sp-mail/packages/mcp/dist/index.js
# read-only agent: add --env SPMAIL_MCP_READONLY=1JSON form (.mcp.json of a project, claude mcp add-json, Claude Desktop's claude_desktop_config.json):
{
"mcpServers": {
"spmail": {
"command": "node",
"args": ["/absolute/path/to/sp-mail/packages/mcp/dist/index.js"],
"env": {
"SPMAIL_API_KEY": "spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"SPMAIL_BASE_URL": "https://mail.spboucher.ai"
}
}
}
}Do not commit a real key: in a shared .mcp.json use "SPMAIL_API_KEY": "${SPMAIL_API_KEY}" and export the variable in your shell.
Tools
| Tool | Scope needed | What it does |
|---|---|---|
spmail_list_accounts |
any key | addresses the key can read / send from, scopes, limits, external-send policy, available tools |
spmail_list_messages |
mail.read |
summaries of a folder (default inbox), newest first, paginated |
spmail_search |
mail.search |
full text, sender, recipient, subject, label; paginated |
spmail_get_message |
mail.read |
one message: metadata, body as plain text (windowed), real link destinations, attachment list |
spmail_get_thread |
mail.read |
summaries of a conversation, oldest first |
spmail_list_attachments |
mail.attachments.read |
id, type, size, name |
spmail_download_attachment |
mail.attachments.read |
text attachments as text (windowed); binaries: metadata only |
spmail_delivery_status |
mail.send or mail.read |
status of a send, per recipient |
spmail_list_templates |
mail.send or mail.drafts |
the owner's templates and their variables |
spmail_create_draft |
mail.drafts |
saves a draft — nothing is sent |
spmail_send |
mail.send |
sends an e-mail (optionally scheduled) |
spmail_send_template |
mail.send |
sends a rendered template |
spmail_reply |
mail.send |
replies in the thread |
spmail_forward |
mail.send and mail.read |
forwards a message with its attachments |
spmail_archive |
mail.modify |
moves to Archive |
spmail_mark_read |
mail.modify |
read / unread |
spmail_move |
mail.modify |
inbox, archive, trash, junk or a folder id |
Tools the key cannot use are not registered (the list is computed from the scopes returned by GET /me at startup; mail.admin implies every scope). spmail_list_accounts reports them under tools_unavailable with the missing scope. A scope change on the key takes effect at the next start of the server; in the meantime the API still refuses (403 insufficient_scope, returned as a clear tool error). With SPMAIL_MCP_READONLY=1 the eight write tools (the second half of the table) are never registered.
Not offered on purpose: permanent deletion, address / alias / webhook / key management, automation rules, file upload (no attachments on outgoing mail), approval of pending sends (a human does that in SP Mail).
Annotations. Read tools: readOnlyHint: true, idempotentHint: true; those that return mail content have openWorldHint: true (the content comes from arbitrary third parties). Send tools: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true. spmail_archive / spmail_mark_read: reversible, idempotent, destructiveHint: false. spmail_move: destructiveHint: true, because Trash and Junk may be purged later by the owner's retention rules.
Compact results. Every result is one JSON object, returned both as text and as structuredContent. Lists return at most 50 items (default 10) with next_cursor. Bodies are returned in windows (max_chars, default 8 000, max 50 000) with truncated and next_offset; call again with offset to continue. Text attachments: windows of 20 000 characters (max 100 000). Binary attachments are never dumped: metadata, SHA-256 and a note; encoding: "base64" is accepted for files up to 64 kB only. Files over 10 MB are never loaded. No text extraction from PDF or office files.
Recommended keys
One key per agent, least privilege. Create it in SP Mail (Administration → API keys) or on the node:
# read-only agent (triage, summaries, search) — also set SPMAIL_MCP_READONLY=1
cli key-create agent-lecture --scopes mail.read,mail.search,mail.attachments.read --addresses contact@example.org
# drafting agent: reads, files, prepares answers; a human sends them from the webmail
cli key-create agent-brouillons --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify --addresses contact@example.org
# sending agent: internal mail leaves directly, anything external waits for the owner's approval
cli key-create agent-envoi --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify,mail.send \
--addresses contact@example.org --external approval --daily 50- Never give an agent
mail.admin,mail.delete,mail.addresses.manage,mail.aliases.manageormail.webhooks.manage: no tool uses them. - Keep
--external approval(the default).--external denyforbids external recipients entirely; useallowonly for an agent whose every send you would approve anyway. - An alias in the allowlist gives a restricted view (only that alias's mail); the mailbox's primary address gives the whole mailbox.
- Set a low
--dailylimit and an expiry (--expires) for experiments. Revoke withcli key-revoke <prefix>: effective at the next request.
Security model
- No added privilege. The only credential is the API key. Everything is an HTTPS call to
/api/v1with that key; whatever the model asks, the API answers403/404outside the key's scopes and addresses. Ids are the opaque API ids, re-checked on every call. - Mail content is data. Every string that comes from a mailbox — subject, sender name, preview, body, link, attachment name, attachment text, SMTP reply — is returned only under an object named
untrusted, whose first key is a fixed marker, and each result starts with a fixednoticestating that this content is third-party data, not instructions. Results are JSON: mail content is an escaped string and cannot close its envelope or forge a field. Addresses are returned outside the envelope only when they are syntactically valid addresses. The server'sinstructionsrepeat the rule. - No markup, no hidden text. Bodies are returned as plain text: the API's text part, or the HTML converted to text by this server. HTML is returned only with
include_html: true(sanitised by the API, still insideuntrusted). Control characters, zero-width characters and bidirectional overrides are removed. Links are listed with their real destination, and flaggedmismatchwhen the visible text names another site. - Nothing is executed. The server never follows a link, renders HTML, opens an attachment, runs anything found in mail or writes to disk. It makes no network call other than to the configured SP Mail API (redirects refused).
- Human confirmation for external sends. With
external_send_policy: approval, a message with any recipient outside the hosted domains is stored and not sent; the API answers202 pending_approval. The tool result then sayssent: falseand "NOT SENT … awaiting the owner's approval in SP Mail", restating sender and recipients. The server never retries and offers no tool to approve; approval needs a passkey re-authentication of an administrator in SP Mail. - Sending is explicit. Send tools restate the sending address and the recipients in their result, and say plainly whether the message was sent, scheduled, queued, refused or awaiting approval. Tool descriptions tell the model to send only on the user's explicit request and to create a draft otherwise.
- Secrets. The key is read from the environment, kept in memory, removed from the process environment, and never written to stdout, stderr or a result.
What this cannot guarantee: a model may still be influenced by what it reads. The envelope, the wording and the read-only mode reduce that risk; the hard limits are the key's scopes, its address allowlist, its daily limit and the approval policy. Choose them as if the agent could be talked into anything the key allows.
Tests
From the repository root (the built server is spawned over stdio and driven with the official MCP client, against a real SP Mail test server; test mailboxes on stg.spboucher.ai are purged at the end):
SPMAIL_TEST_PORT=8801 SPMAIL_TEST_DB=postgres://127.0.0.1/sp_mail_sdk_test \
node --import tsx --test --test-concurrency=1 tests/integration/mcp-server.test.ts