Skip to main content
Glama
ericmaddox

agent-jmap-mcp

by ericmaddox
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

agent-jmap-mcp

PyPI Version CI Python Version License: MIT MCP Protocol Ruff

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

Related MCP server: mcp-imap

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:

Variable

Description

Example / Default

JMAP_SESSION_URL

JMAP Session discovery URL

https://api.fastmail.com/.well-known/jmap

JMAP_API_TOKEN

Bearer API token

fmu1-...

JMAP_ACCOUNT_ID

Optional target account ID

Auto-discovered from session if omitted

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

Tool Name

Parameters

Description

jmap_list_mailboxes

None

Returns metadata for all mailboxes (IDs, names, roles, unread/total counts).

jmap_list_emails

mailbox, limit, unread_only, query, from_address, subject_contains

Queries email headers with filtering, search conditions, and sorting.

jmap_get_email

email_id (str), mark_as_read (bool)

Fetches full email body (converted to markdown if HTML), headers, and attachments.

jmap_get_thread

thread_id (str)

Fetches full multi-message conversation thread chronologically.

jmap_download_attachment

blob_id (str), filename (str), save_directory (str)

Downloads binary attachment from JMAP server and saves to disk.

jmap_send_email

to (list), subject (str), body (str), from_address (str), cc (list), bcc (list), draft_only (bool)

Atomically creates and submits an outgoing message (or saves to drafts).

jmap_triage_inbox

mailbox (str), limit (int), unread_only (bool)

Analyzes recent messages and returns categorization, priorities, and action items.

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

License

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • IMAP Email MCP Server

    jdickey1
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to read, search, compose, and send emails by connecting to any IMAP/SMTP provider. It supports comprehensive mailbox management, including draft handling and message deletion, directly through natural language.
    10
    153 npm
    10
    MIT

  • mcp-imap

    andrewmalov
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.
    MIT

  • Mail MCP Server

    martinzarfl
    A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to send, read, and manage emails via SMTP and IMAP, with support for attachments, threads, and mailbox organization.
    16
    17 npm
    1
    MIT

  • fastmail-mcp

    eduardobrito21
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to manage Fastmail email accounts via JMAP, including reading, sending, organizing emails, and handling mailboxes, drafts, and masked emails.
    43
    MIT