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

• Get Emails: Retrieve specific emails by ID with full details

• 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

Email Composition

• Send Email: Compose and send new emails with support for plain text and HTML

• Reply to Email: Reply to existing emails with 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

• Rich error handling and connection management

• Functional programming patterns throughout

• TypeScript support with strong typing

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 agent of choice:

Usage

Environment Variables

Available Tools

search_emails

Search for emails with 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 specific mailbox

• hasKeyword (optional): Filter by keyword (e.g., '$seen', '$flagged')

• notKeyword (optional): Exclude by keyword

• before (optional): Only emails before date (ISO datetime)

• after (optional): Only emails after date (ISO datetime)

• limit (optional): Max 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 list of mailboxes/folders.

Parameters:

• parentId (optional): Filter by parent mailbox

• limit (optional): Max 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

Delete emails permanently.

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 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

JMAP Server Compatibility

This server should work 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

Testing

Architecture

The server is built using:

• Deno: Modern JavaScript/TypeScript runtime

• @modelcontextprotocol/sdk: MCP server framework

• jmap-jam: Lightweight, typed JMAP client

• Zod: Runtime type validation

Security

• All input is validated using Zod schemas

• Environment variables are used for sensitive configuration

• No secrets are logged or exposed in responses

• Follows JMAP security best practices

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes following the functional programming style

4. Test your changes thoroughly

5. Submit a pull request

License

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