jmap-mcp

jmap-mcp is a Model Context Protocol (MCP) server for interacting with JMAP (JSON Meta Application Protocol) mail servers. It is built with Deno and uses the jmap-jam client library under the hood.

Purpose This repository is a Deno workspace containing a usable JMAP mail client, as well as an MCP server built on top of that client. The client package accesses the JMAP protocol via jmap-jam; the MCP package adapts those typed operations into callable tools for agents that support MCP.

Main capabilities Mail management tools:

• Search mail: supports text queries, sender/recipient filtering, date ranges, and keywords; all filter conditions are combined with AND.
• Get mail: retrieves specified mail by ID, with a configurable set of returned properties.
• Get mail thread: retrieves the mail thread (conversation chain).
• Mark mail: mark as read/unread, flagged/unflagged.
• Move mail: move mail to a mailbox.
• Adjust mail mailbox membership: add or remove selected mailbox memberships while preserving unspecified memberships.
• Delete mail: permanently delete mail.

Mailbox management:

• Get mailboxes: list all mailboxes/folders with support for hierarchical structure, which can be used to find the mailbox IDs required by other tools.

Incremental sync:

• Get mail changes: based on the previous state, retrieve the IDs of mail created, updated, or destroyed since then (state-based incremental tracking).
• Get search updates: retrieve mail added or removed since the queryState of the previous search query.

Mail composition:

• Send mail: compose and send new mail, with support for plain text and HTML.
• Reply to mail: reply to an existing mail, automatically handling headers and supporting reply-all.

Key features also include: full compliance with JMAP RFC 8620/8621 via jmap-jam; comprehensive input validation using Zod schemas; pagination support for all list operations; state-based incremental sync for efficient polling; robust error handling and connection management; capability-based tool registration (read-only, submit); strongly typed TypeScript support.

Usage Environment requirements: Deno v2 or higher; a JMAP-compliant mail server (e.g., Cyrus IMAP, Stalwart Mail Server,FastMail); valid JMAP authentication credentials.

It is recommended to install the Claude Code plugin through the plugin marketplace, and then configure the required environment variables in the MCP server settings. You can also add the configuration to the agent of your choice; if you are not using FastMail, replace api.fastmail.com in --allow-net with your JMAP server hostname.

Client reusable: standalone applications can directly import @wyattjoh/jmap without creating an MCP server or transport layer; see packages/jmap/README.md.

Tool overview (excerpted description)

• get_mailboxes: List mailboxes/folders and their IDs, names, and metadata. It should be called first to obtain the mailbox IDs required by search_emails (inMailbox) and move_emails (mailboxId). Common names: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk. Optional parameters parentId (filter by parent mailbox ID), limit (1-200, default 100), position (pagination start position).
• search_emails: Search emails with filter conditions, all conditions are combined with AND, and only email IDs are returned—use get_emails to retrieve content. The result includes queryState, which can be used for incremental synchronization via get_search_updates. Optional parameters include query, body, from, to, subject, inMailbox, hasKeyword, notKeyword, allInThreadHaveKeyword, someInThreadHaveKeyword, before, after, limit (1-100, default 50), position (default 0).
• get_emails: Retrieve specified emails by ID. It is recommended to use properties to request only the needed fields, avoiding pulling all properties and causing an oversized payload. ids is an array of email IDs (1-50). Recommended property sets: summary ["id", "subject", "from", "to", "receivedAt", "preview"]; full read ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]. Note that retrieving the body requires including both bodyValues and textBody/htmlBody.
• get_threads: Retrieve email threads by ID. The thread ID comes from the threadId property in the get_emails response. It returns the email IDs in each thread, then call get_emails on those IDs to retrieve content. ids is an array of thread IDs (1-20).
• get_email_changes: Retrieve the IDs of emails created, updated, or destroyed since the last state, using the state string from the get_emails response. Parameters: sinceState; optional maxChanges (1-500), fetchEmails (default false, automatically fetch full email details for changed IDs), properties (the properties to fetch when fetchEmails is true).
• get_search_updates: Retrieve changes to the previous search query after queryState. You must use the same filter parameters as the original search_emails call. Parameters: sinceQueryState, and all filter parameters of search_emails (must match the original query).
• mark_emails: Mark emails as read/unread or flagged/unflagged. Parameters: ids (1-100), seen (true read / false unread), flagged (true flagged / false unflagged).
• move_emails: Move emails to another mailbox. You can use get_mailboxes to find the target mailbox ID. Parameters: mailboxId.
• patch_email_mailboxes: Add or remove membership in selected mailboxes without replacing unspecified memberships, supporting label-like workflows and compound classification. Parameters: addMailboxIds, removeMailboxIds; at least one mailbox must be added or removed, and the same mailbox cannot appear in both arrays at the same time.
• delete_emails: Permanently delete emails (irreversible). If recoverable deletion is needed, it is recommended to first use move_emails to move them to Trash.
• send_email: Send a new email; textBody or htmlBody (or both) must be provided. Parameters: to (array of recipients, name optional, email required), cc, bcc, subject, textBody, htmlBody, identityId (optional, used to specify the sending identity; if omitted, the server default is used).
• reply_email: Reply to an existing email, automatically setting To/CC, the Re: subject prefix, and thread headers (In-Reply-To, References). Parameters: emailId, replyAll (default false), subject (optional, default Re: <original subject>).

JMAP Server Compatibility Can be used with any JMAP-compliant mail server, including: Cyrus IMAP 3.0+, Stalwart Mail Server, FastMail (commercial), Apache James (when JMAP is supported).

Development and Structure The repository is a Deno workspace containing two independently publishable packages:

• packages/jmap / @wyattjoh/jmap: functional connection, retrieval, incremental sync, change, and submission operations.
• packages/jmap-mcp / @wyattjoh/jmap-mcp: MCP schemas, tool adapters, capability registration, and the stdio entry point. The MCP adapters call the client package directly. JMAP behavior belongs to the client package; transport-layer validation and user-facing tool contracts belong to the MCP package.

Security: all input is validated using Zod schemas; sensitive configuration is passed via environment variables; secrets are not logged or exposed in logs or responses; JMAP security best practices are followed.

How to contribute: Fork the repository, create a feature branch, make changes in a functional programming style, test thoroughly, and submit a pull request.

License: MIT, see the LICENSE file for details.

Related projects: jmap-jam (JMAP client library), Model Context Protocol (MCP specification), JMAP RFC 8620 (JMAP core protocol), JMAP RFC 8621（JMAP for Mail）。