jmap-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
jmap-mcp
A small MCP server (stdio, Bun) for one JMAP mail account (RFC 8620, RFC 8621 incl. submission).
It is written to be read in an afternoon: about 2,500 lines of TypeScript, three runtime dependencies
(@modelcontextprotocol/server, zod, htmlparser2), no JMAP client library.
Tested against Stalwart, but it only uses standard JMAP and runs against a mock server in its tests.
Several accounts are several entries in your MCP client config. Each entry starts the same program with its own environment. There is no config file.
Reading is on by default and can be switched off (JMAP_READ=false) for send-only setups. Drafts, sending, organizing and attachments are switched on one by one. The defaults are restrictive. Sending can be opened up as far as you want (JMAP_ALLOWED_RECIPIENTS=*, JMAP_SEND_LIMIT_PER_HOUR=unlimited).
Threat model
Incoming mail is hostile input. The goal: a prompt injection in a mail cannot do more than the environment variables allow.
What the server enforces in code (not in the model):
Protection | How |
Recipient allowlist | Applies to To, Cc and Bcc (unless |
Sender |
|
Rate limit |
|
Audit log | JSON lines on stderr: time, account name, recipients, subject length, result. Never mail text, never credentials. |
Untrusted content | Everything from a mail (subject, addresses, body, file names, previews) is returned in |
Sanitizing | Zero-width and bidi characters, control characters, hidden HTML ( |
Network | HTTPS only ( |
Secrets | Held in a wrapper that prints as |
No delete, no config change | There is no delete tool. Moving to Trash is refused. No tool changes configuration. |
What it does not protect against:
A mail can still persuade the model to do something inside the allowed scope: send a text of its choosing to an allowed recipient, mark or move mail (if
JMAP_ORGANIZE), read mail and attachments and repeat their content to an allowed recipient. Keep the allowlist short and use the permission rules below.With
JMAP_ALLOWED_RECIPIENTS=*andJMAP_SEND_LIMIT_PER_HOUR=unlimitednothing limits where mail goes or how much is sent. A prompt injection can then mail mailbox content to anyone. Use these settings only for send-only accounts (JMAP_READ=false) or keep theaskpermission rules in your client. The address syntax and the sender identity are still checked.The fencing is a mitigation, not a guarantee. Models can still be fooled by text inside a fence.
Whoever can edit your MCP client config can change every setting. Protect that file.
Plain text only. The server sends no HTML and no attachments.
Data you send to an allowed recipient is not under this server's control any more.
A compromised machine or compromised dependencies. Versions are pinned and
bun.lockis committed, but nothing is audited for you.
Related MCP server: agent-jmap-mcp
Install and start
"command": ["bunx", "@timootten/jmap-mcp@0.1.2"]The package ships TypeScript (bin points at src/index.ts with a #!/usr/bin/env bun shebang). Bun runs it directly, no build step. Pin an exact version.
Environment variables
All variables are validated at start. Any error ends the process with a message on stderr (fail closed). Any unknown JMAP_* variable is an error.
Variable | Required | Meaning |
| yes | JMAP session URL, https only |
| no | Replaces the origin of |
| yes (Basic) | User and password or app password. Taken as is, including inner spaces ( |
| yes (Bearer) | Bearer token. Exactly one of the two login methods. |
| no | Short name for logs and the state file. Default: user name. |
| no |
|
| no |
|
| if | Comma-separated exact addresses or |
| no | Default |
| no |
|
| no |
|
| no |
|
| no | Absolute path for the rate-limit file. Default |
| no |
|
Booleans are exactly true or false. True, 1, yes and a trailing space are startup errors.
If the server has no urn:ietf:params:jmap:submission capability, sending is not offered even with JMAP_SEND=true (a warning goes to stderr, reading still works).
If the session cannot be reached at start, the server still starts. The first call reports the problem and later calls retry.
Tools
Tool | Switch | Notes |
| always | name, user, enabled capabilities, number of allowlist patterns, identities. No credentials. |
|
| read only, paged ( |
|
| saves to Drafts, sends nothing |
|
| allowlist, rate limit, audit |
|
| max 50 ids, no move to Trash |
|
| text up to 100 KB, images (png, jpeg, gif, webp) up to 500 KB |
A tool is only registered when its switch is on, and every call checks the switch again. All tools carry readOnlyHint, destructiveHint, idempotentHint and openWorldHint.
Sending creates a draft ($draft, Drafts mailbox) with Email/set, then EmailSubmission/set with an explicit envelope equal to the checked recipients. onSuccessUpdateEmail removes $draft and moves the mail to Sent.
OpenCode
Checked against the config schema of OpenCode 2.2.7 (opencode debug config loads the example without errors). Servers live under mcp.servers.<name>, rules in the permissions array.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"mail-shadehost-eu": {
"type": "local",
"command": ["bunx", "@timootten/jmap-mcp@0.1.2"],
"cwd": "~",
"environment": {
"JMAP_SESSION_URL": "https://stalwart.example.eu/jmap/session",
"JMAP_API_ORIGIN": "https://stalwart.example.eu",
"JMAP_USERNAME": "timo@example.eu",
"JMAP_PASSWORD": "{env:STALWART_PW_SHADEHOST_EU}",
},
},
"mail-timootten-com": {
"type": "local",
"command": ["bunx", "@timootten/jmap-mcp@0.1.2"],
"cwd": "~",
"environment": {
"JMAP_SESSION_URL": "https://stalwart.example.eu/jmap/session",
"JMAP_API_ORIGIN": "https://stalwart.example.eu",
"JMAP_USERNAME": "hi@example.com",
"JMAP_PASSWORD": "{env:STALWART_PW_TIMOOTTEN_COM}",
"JMAP_SEND": "true",
"JMAP_ALLOWED_RECIPIENTS": "friend@example.net,@example.org",
},
},
},
},
"permissions": [
{ "action": "mail-timootten-com_send_email", "resource": "*", "effect": "ask" },
{ "action": "mail-timootten-com_reply_email", "resource": "*", "effect": "ask" },
{ "action": "mail-timootten-com_send_draft", "resource": "*", "effect": "ask" },
{ "action": "edit", "resource": "~/.config/opencode/opencode.jsonc", "effect": "deny" },
],
}Tool names are <server>_<tool>. The ask rules make OpenCode ask before every send. The deny rule is meant to stop the agent from editing the file that holds the allowlist.
Limits of this setup:
The
editrule only covers OpenCode's own edit tools. A shell tool can still change the file unless you also restrictshell. Better: make the file read-only for the user that runs the agent, or manage it from outside the agent's reach.Whether the
askanddenyrules take effect on MCP tools and files in your setup was not tested (OpenCode has no offline way to evaluate permissions, and a real test would need a send). Test it once with a harmless call before relying on it.If the config is rendered from a repo (for example by an entrypoint script that copies it on every start), edits inside the container do not persist anyway.
Stalwart rights
An app password that may send needs: authenticate, the jmapMailbox* and jmapEmail* read rights, emailSend, jmapEmailCreate, jmapEmailUpdate, jmapBlobUpload, and jmapEmailSubmission{Get,Changes,Query,Create}.
Without jmapEmailDestroy the server cannot delete anything for good. This is intended.
Read-only accounts need only the read rights. JMAP_ORGANIZE needs jmapEmailUpdate, JMAP_DRAFTS needs jmapEmailCreate.
See CONTRIBUTING.md for development, commit rules and the release process.
Development
bun install --frozen-lockfile
bun run check # tsc + oxlint + oxfmt --check
bun testOptional read-only live test (skipped unless JMAP_LIVE_TEST=1):
JMAP_LIVE_TEST=1 JMAP_LIVE_SESSION_URL=... JMAP_LIVE_USERNAME=... JMAP_LIVE_PASSWORD=... \
[JMAP_LIVE_API_ORIGIN=...] bun test test/live.test.tsLayout: config.ts (env), address.ts (parsing, allowlist), sanitize.ts and fence.ts (untrusted content), jmap.ts (HTTP and session), mail.ts (read and update calls), send.ts (drafts and submission), ratelimit.ts, log.ts, server.ts (tools), index.ts (start).
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Read and search FranklyMail email and prepare drafts, replies, and forwards for human approval.
Related MCP Servers
- FlicenseBqualityBmaintenanceEnables reading and writing email through IMAP and SMTP accounts using natural language via the Model Context Protocol.1619 npm-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to manage email over JMAP, including inspecting mailboxes, searching and retrieving messages, navigating threads, downloading attachments, triaging inboxes, and sending emails atomically via HTTP.42 PyPIMIT
- FlicenseNot gradedqualityBmaintenanceEnables reading and drafting emails via IMAP, including searching and managing drafts, through natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude and ChatGPT to read, search, and organize mail in a user's own email account, including folders, threads, attachments, drafts, and optional sending, with per-user permission levels and OAuth-secured remote connections.MIT