Skip to main content
Glama
jmap-mcp

jmap-mcp

by timootten

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 JMAP_ALLOWED_RECIPIENTS=*, which allows any recipient but still checks the address syntax), also for reply_email and send_draft. One plain address per entry. Addresses are parsed strictly (no display names, comments, lists, non-ASCII) and compared lowercase. Patterns are exact addresses or @domain (no wildcards, no subdomains). One bad recipient rejects the whole message.

Sender

from must match a JMAP identity of the account.

Rate limit

JMAP_SEND_LIMIT_PER_HOUR, sliding window, in memory and in a small file in JMAP_STATE_DIR. If the file is unreadable or corrupt, sending is refused.

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 [UNTRUSTED_<nonce>] ... [/UNTRUSTED_<nonce>] blocks. The nonce is new for every call and every line inside carries it. Marker-like strings in the content are removed. The server instructions tell the model that these blocks are data.

Sanitizing

Zero-width and bidi characters, control characters, hidden HTML (display:none, visibility:hidden, opacity:0, font size 0, hidden, comments, scripts, styles), tracking pixels and Markdown images are removed. A visible warning with the character count is appended when something was removed. All scans are linear time (tests include 300,000 repetitions of <style ).

Network

HTTPS only (http for loopback with JMAP_ALLOW_INSECURE_LOCALHOST=true). Redirects are only followed inside the same origin. Credentials go only to the session origin and JMAP_API_ORIGIN. A session that names another host is rejected. Timeouts and size limits on every response.

Secrets

Held in a wrapper that prints as [redacted], removed from process.env after start, redacted from all log lines and error text. Server error text is shortened and cleaned before it reaches the model.

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=* and JMAP_SEND_LIMIT_PER_HOUR=unlimited nothing 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 the ask permission 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.lock is 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

JMAP_SESSION_URL

yes

JMAP session URL, https only

JMAP_API_ORIGIN

no

Replaces the origin of apiUrl, uploadUrl, downloadUrl, eventSourceUrl from the session. Needed when the server advertises a host that is not reachable from outside (seen with Stalwart).

JMAP_USERNAME + JMAP_PASSWORD

yes (Basic)

User and password or app password. Taken as is, including inner spaces (app xxxxxxxx). At most one trailing line ending is removed.

JMAP_TOKEN

yes (Bearer)

Bearer token. Exactly one of the two login methods.

JMAP_NAME

no

Short name for logs and the state file. Default: user name.

JMAP_READ

no

false removes list_mailboxes, search_emails, get_email, get_thread and list_identities, for send-only setups. Default true. reply_email and send_draft still read the mail or draft they work on.

JMAP_SEND

no

true or false (default false)

JMAP_ALLOWED_RECIPIENTS

if JMAP_SEND=true

Comma-separated exact addresses or @domain patterns, or a lone * for any recipient (a warning is logged at start). * cannot be mixed with other entries.

JMAP_SEND_LIMIT_PER_HOUR

no

Default 10. A whole number from 1 to 100000, or unlimited (a warning is logged at start, no state file is used).

JMAP_DRAFTS

no

create_draft. Default false

JMAP_ORGANIZE

no

mark_emails, move_emails. Default false

JMAP_ATTACHMENTS

no

get_attachment. Default false

JMAP_STATE_DIR

no

Absolute path for the rate-limit file. Default $XDG_STATE_HOME/jmap-mcp (or ~/.local/state/jmap-mcp)

JMAP_ALLOW_INSECURE_LOCALHOST

no

true allows http for localhost, 127.0.0.1, [::1] only. Default false

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

account_info

always

name, user, enabled capabilities, number of allowlist patterns, identities. No credentials.

list_mailboxes, search_emails, get_email, get_thread, list_identities

JMAP_READ (default on)

read only, paged (limit, position, offset)

create_draft

JMAP_DRAFTS

saves to Drafts, sends nothing

send_email, reply_email, send_draft

JMAP_SEND

allowlist, rate limit, audit

mark_emails, move_emails

JMAP_ORGANIZE

max 50 ids, no move to Trash

get_attachment

JMAP_ATTACHMENTS

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 edit rule only covers OpenCode's own edit tools. A shell tool can still change the file unless you also restrict shell. Better: make the file read-only for the user that runs the agent, or manage it from outside the agent's reach.

  • Whether the ask and deny rules 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 test

Optional 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.ts

Layout: 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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      Enables reading and writing email through IMAP and SMTP accounts using natural language via the Model Context Protocol.
      16
      19 npm
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables reading and drafting emails via IMAP, including searching and managing drafts, through natural language.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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