Jmap MCP

🚀 JMAP MCP Server

This JMAP MCP Server offers a suite of tools for seamless interaction with JMAP (JSON Meta Application Protocol) email servers. It's built with Deno and leverages the @htunnicliff/jmap-jam client library.

✨ Features

Email Management Tools

• Search Emails: Conduct searches using text queries, sender/recipient filters, date ranges, and keywords.
• Get Emails: Retrieve specific emails by their IDs, complete with full details.
• Get Threads: Fetch email threads (conversation chains).
• Mark Emails: Mark emails as read/unread or flagged/unflagged.
• Move Emails: Transfer emails between different mailboxes.
• Delete Emails: Permanently delete emails.

Mailbox Management

• Get Mailboxes: List all mailboxes/folders, with support for hierarchical display.

Email Composition

• Send Email: Compose and send new emails, supporting both plain text and HTML formats.
• Reply to Email: Respond to existing emails, with an option for reply-all.

Key Capabilities

• Full compliance with JMAP RFC 8620/8621 through the jmap - jam library.
• Comprehensive input validation using Zod schemas.
• Pagination support for all list operations.
• Robust error handling and connection management.
• Adoption of functional programming patterns throughout the codebase.
• Strong typing support with TypeScript.

📦 Installation

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 preferred agent:

{
  "mcpServers": {
    "fastmail": {
      "type": "stdio",
      "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.1.1"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "API_TOKEN"
      }
    }
  }
}

💻 Usage Examples

Environment Variables

Available Tools

search_emails

Search for emails using various filters. Parameters:

• query (optional): Text search query.
• from (optional): Filter by sender email address.
• to (optional): Filter by recipient email address.
• subject (optional): Filter by subject text.
• inMailbox (optional): Search within a specific mailbox.
• hasKeyword (optional): Filter by keyword (e.g., '$seen', '$flagged').
• notKeyword (optional): Exclude by keyword.
• before (optional): Only emails before a specific date (ISO datetime).
• after (optional): Only emails after a specific date (ISO datetime).
• limit (optional): Maximum number of results (1 - 100, default: 50).
• position (optional): Starting position for pagination (default: 0).

get_emails

Retrieve specific emails by their IDs. Parameters:

• ids: Array of email IDs (1 - 50 IDs).
• properties (optional): Specific properties to return.

get_mailboxes

Get a list of mailboxes/folders. Parameters:

• parentId (optional): Filter by parent mailbox.
• limit (optional): Maximum number of results (1 - 200, default: 100).
• position (optional): Starting position for pagination.

get_threads

Get email threads by their IDs. Parameters:

• ids: Array of thread IDs (1 - 20 IDs).

mark_emails

Mark emails with keywords (read/unread, flagged/unflagged). Parameters:

• ids: Array of email IDs (1 - 100 IDs).
• seen (optional): Mark as read (true) or unread (false).
• flagged (optional): Mark as flagged (true) or unflagged (false).

move_emails

Move emails to a different mailbox. Parameters:

• ids: Array of email IDs (1 - 100 IDs).
• mailboxId: Target mailbox ID.

delete_emails

Permanently delete emails. Parameters:

• ids: Array of email IDs (1 - 100 IDs).

send_email

Send a new email. Parameters:

• to: Array of recipients with name and email.
• cc (optional): Array of CC recipients.
• bcc (optional): Array of BCC recipients.
• subject: Email subject.
• textBody (optional): Plain text body.
• htmlBody (optional): HTML body.
• identityId (optional): Identity to send from.

reply_to_email

Reply to an existing email. Parameters:

• emailId: ID of the email to reply to.
• replyAll (optional): Reply to all recipients (default: false).
• subject (optional): Custom reply subject.
• textBody (optional): Plain text body.
• htmlBody (optional): HTML body.
• identityId (optional): Identity to send from.

📚 Documentation

JMAP Server Compatibility

This server is compatible with any JMAP - compliant email server, including:

• Cyrus IMAP 3.0+
• Stalwart Mail Server
• FastMail (commercial)
• Apache James (with JMAP support)

Development

Running in Development

deno run --allow-env --allow-net --watch src/mod.ts

Testing

# Test connection
deno run --allow-env --allow-net src/mod.ts

Architecture

The server is built using:

• Deno: A modern JavaScript/TypeScript runtime.
• @modelcontextprotocol/sdk: An MCP server framework.
• jmap - jam: A lightweight, typed JMAP client.
• Zod: A runtime type validation library.

Security

• All input is validated using Zod schemas.
• Environment variables are used for sensitive configuration.
• No secrets are logged or exposed in responses.
• Adherence to JMAP security best practices.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make changes following the functional programming style.
4. Thoroughly test your changes.
5. Submit a pull request.

📄 License

This project is released under the MIT License. See 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.