MCP Directory

How to add JMAP MCP Server to Windsurf

MCP server for interacting with JMAP email servers (FastMail, Stalwart, Cyrus, James) — search, read, send, and manage email. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 172★ · stdio · apikey

Windsurf config for JMAP MCP Server

deno run --allow-net=api.fastmail.com --allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID jsr:@wyattjoh/jmap-mcp@0.6.4
{
  "mcpServers": {
    "jmap-mcp-server": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.4"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the JMAP MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5JMAP MCP Server's tools become available to Cascade.

Before you start

  • Deno v1.40 or later
  • A JMAP-compliant email server (e.g., Cyrus IMAP, Stalwart Mail Server, FastMail, Apache James)
  • Valid JMAP authentication credentials (bearer token)

What JMAP MCP Server can do in Windsurf

get_mailboxes

List mailboxes/folders with their IDs, names, and metadata. Call this first to get mailbox IDs needed by search_emails (inMailbox) and move_emails (mailboxId). Supports parentId, limit (1-200, default 100), and position pagination.

search_emails

Search emails with filters (query, body, from, to, subject, inMailbox, hasKeyword, notKeyword, thread-keyword filters, before/after dates), all AND'd together. Returns email IDs plus a queryState for incremental sync. Supports limit (1-100, default 50) and position pagination.

get_emails

Retrieve specific emails by their IDs (1-50). Use the properties parameter to request only needed fields; include bodyValues plus textBody/htmlBody to get body content.

get_threads

Get email threads (conversation chains) by their IDs (1-20). Thread IDs come from the threadId property of get_emails responses. Returns email IDs per thread.

get_email_changes

Get IDs of emails created, updated, or destroyed since a previous state (state-based delta tracking). Supports maxChanges (1-500), optional fetchEmails to auto-fetch details, and properties selection.

get_search_updates

Get additions/removals within a previous search query since its queryState. Must use the same filter parameters as the original search_emails call. Supports maxChanges (1-500).

mark_emails

Mark emails (1-100 IDs) as read/unread (seen) or flagged/unflagged.

move_emails

Move emails (1-100 IDs) to a different mailbox specified by mailboxId (obtained from get_mailboxes).

Security

Authentication uses a JMAP bearer token supplied via the JMAP_BEARER_TOKEN environment variable; do not commit it. All input is validated using Zod schemas and no secrets are logged or exposed in responses. The Deno --allow-net flag should be scoped to your JMAP server's hostname (defaults to api.fastmail.com). The delete_emails tool permanently deletes email and cannot be undone — prefer move_emails to Trash for recoverable deletion.

JMAP MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the JMAP MCP Server config there under the "mcpServers" key and restart the client.

Is JMAP MCP Server safe to use with Windsurf?

Authentication uses a JMAP bearer token supplied via the JMAP_BEARER_TOKEN environment variable; do not commit it. All input is validated using Zod schemas and no secrets are logged or exposed in responses. The Deno --allow-net flag should be scoped to your JMAP server's hostname (defaults to api.fastmail.com). The delete_emails tool permanently deletes email and cannot be undone — prefer move_emails to Trash for recoverable deletion.

Which email servers are supported?

Any JMAP-compliant server, including Cyrus IMAP 3.0+, Stalwart Mail Server, FastMail (commercial), and Apache James with JMAP support.

How do I authenticate?

Set JMAP_SESSION_URL to your server's JMAP session URL and JMAP_BEARER_TOKEN to a bearer token. JMAP_ACCOUNT_ID is optional and auto-detected if not provided.

How do I use it with a non-FastMail server?

Replace api.fastmail.com in the Deno --allow-net flag with your JMAP server's hostname, and set JMAP_SESSION_URL accordingly.

View repo Full JMAP MCP Server page