jmap-mcp

JMAP MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with JMAP (JSON Meta Application Protocol) email servers. Built with Deno and using the @htunnicliff/jmap-jam client library.

Features

Email Management Tools

• Search Emails: Search emails with text queries, sender/recipient filters, date ranges, and keywords. All filters are AND'd together.
• Get Emails: Retrieve specific emails by ID with configurable property selection
• Get Threads: Retrieve email threads (conversation chains)
• Mark Emails: Mark emails as read/unread, flagged/unflagged
• Move Emails: Move emails between mailboxes
• Delete Emails: Delete emails permanently

Mailbox Management

• Get Mailboxes: List all mailboxes/folders with hierarchy support. Use this to find mailbox IDs needed by other tools.

Incremental Sync

• Get Email Changes: Get IDs of emails created, updated, or destroyed since a previous state (state-based delta tracking)
• Get Search Updates: Get additions/removals within a previous search query since its last queryState

Email Composition

• Send Email: Compose and send new emails with support for plain text and HTML
• Reply to Email: Reply to existing emails with automatic header handling and reply-all support

Key Capabilities

• Full JMAP RFC 8620/8621 compliance via jmap-jam
• Comprehensive input validation with Zod schemas
• Pagination support for all list operations
• State-based incremental sync for efficient polling
• Rich error handling and connection management
• Capability-based tool registration (read-only, submission)
• TypeScript support with strong typing

Installation

Claude Code Plugin (Recommended)

Install via the plugin marketplace:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

Then configure the required environment variables in your MCP server settings.

Prerequisites

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

Setup

Add the following to your agent of choice:

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

Replace api.fastmail.com in --allow-net with your JMAP server's hostname if not using FastMail.

Usage

Environment Variables

Variable	Required	Description
JMAP_SESSION_URL	Yes	JMAP server session URL (usually ends with /.well-known/jmap)
JMAP_BEARER_TOKEN	Yes	Bearer token for authentication
JMAP_ACCOUNT_ID	No	Account ID (auto-detected if not provided)

Available Tools

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). Common names: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

Parameters:

• parentId (optional): Filter by parent mailbox ID
• limit (optional): Max results (1-200, default: 100)
• position (optional): Starting position for pagination

search_emails

Search emails with filters. All filters are AND'd together. Returns only email IDs — use get_emails to fetch content. Results include queryState for incremental sync via get_search_updates.

Parameters: