agent-jmap-mcp

agent-jmap-mcp

A stateless, production-grade JSON Meta Application Protocol (JMAP) client and Model Context Protocol (MCP) server for AI agents, automation pipelines, and developer workflows.

Compliant with RFC 8620 (JMAP Core) and RFC 8621 (JMAP Mail), agent-jmap-mcp allows language models (e.g. Claude, Hermes Agent, GPT-4, Cursor) to inspect mailboxes, search and retrieve messages, navigate conversation threads, download attachments, perform automated inbox triage, and compose/send emails atomically over pure HTTP.

---

Architecture

flowchart TD
    subgraph Host["AI Agent / Host Application"]
        Agent["AI Agent / LLM Client"]
    end

    subgraph MCP["agent-jmap-mcp Server"]
        Server["FastMCP stdio Engine"]
        Tools["Tools Interface<br/>(list, search, get, thread, download, send, triage)"]
        TriageEng["Rule-Based Triage Engine"]
        Converter["HTML-to-Markdown Engine"]
        Client["RFC 8620/8621 JMAP Client"]
    end

    subgraph Upstream["JMAP Email Server"]
        JMAPEndpoint["JMAP API Endpoint<br/>(Fastmail / Stalwart / Cyrus)"]
    end

    Agent <-->|"JSON-RPC / stdio"| Server
    Server --> Tools
    Tools --> TriageEng
    Tools --> Converter
    Tools --> Client
    Client <-->|"Stateless HTTPS (JSON Batches / Binary Streams)"| JMAPEndpoint

---

Key Capabilities

• Stateless HTTP Architecture: Operates over standard HTTPS with bearer token authentication. Avoids persistent IMAP socket overhead and connection timeout state.
• Atomic Operations: Executes message creation and dispatch in a single atomic transaction combining Email/set and EmailSubmission/set.
• Conversation Threading (Thread/get): Full RFC 8621 conversation thread retrieval aggregating multi-turn email dialogues chronologically.
• Binary Attachment Downloads: High-speed streaming downloads for PDF, image, and data attachments via session downloadUrl.
• Rich HTML-to-Markdown Extraction: Automated markdown conversion for HTML-only newsletters and styled emails.
• Session Auto-Discovery: Automatically queries /.well-known/jmap to discover API endpoints, upload/download URLs, and primary account IDs.
• Zero-Footprint Model Context: Optimized JSON payloads structured specifically for minimal LLM context window consumption.
• Automated Inbox Triage: Built-in heuristic classification for inbox sorting (Urgent, Action Required, Personal, Notifications, Newsletters).
• Universal MCP Compatibility: Plugs directly into Claude Desktop, Hermes Agent, Cursor, Zed, and any MCP-compliant environment.

---

Installation

Using uv (Recommended)

uv tool install agent-jmap-mcp

Using pipx or pip

pipx install agent-jmap-mcp
# or
pip install agent-jmap-mcp

---

Configuration

Set the required environment variables:

A .env.example template is provided in the repository.

---

MCP Server Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jmap": {
      "command": "uvx",
      "args": ["agent-jmap-mcp"],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
        "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
      }
    }
  }
}

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  jmap:
    command: "uvx"
    args: ["agent-jmap-mcp"]
    env:
      JMAP_SESSION_URL: "https://api.fastmail.com/.well-known/jmap"
      JMAP_API_TOKEN: "${JMAP_API_TOKEN}"

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "jmap": {
      "command": "uvx",
      "args": ["agent-jmap-mcp"],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
        "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
      }
    }
  }
}

Zed Editor

Add to settings.json:

{
  "context_servers": {
    "jmap": {
      "command": {
        "path": "uvx",
        "args": ["agent-jmap-mcp"],
        "env": {
          "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
          "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
        }
      }
    }
  }
}

---

Available MCP Tools

---

Command Line Interface (CLI)

The package includes a standalone CLI tool agent-jmap:

# Start MCP server over stdio
agent-jmap serve

# List available mailboxes
agent-jmap mailboxes

# List recent emails
agent-jmap list --limit 10
agent-jmap list --unread --query "invoice"

# View specific email
agent-jmap get <email-id>

# View entire conversation thread
agent-jmap thread <thread-id>

# Download binary attachment
agent-jmap download <blob-id> --name report.pdf --output ./downloads

# Run inbox triage
agent-jmap triage --limit 20

# Send email from command line
agent-jmap send --to user@example.com --subject "Status Update" --body "Processing completed."

---

Development and Testing

Setup Environment

git clone https://github.com/ericmaddox/agent-jmap-mcp.git
cd agent-jmap-mcp
uv sync --extra dev

Running Test Suite

uv run pytest -v

Code Formatting and Linting

uv run ruff check .
uv run ruff format .

Building Distribution Packages

uv build

---

RFC Compliance

• RFC 8620: The JSON Meta Application Protocol (JMAP)
• RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail
• RFC 5322: Internet Message Format

---

License

MIT License. Copyright (c) 2026 Eric Maddox. See LICENSE for details.