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:
{
"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
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
search_emails
Search for emails with various filters.
Parameters:
query(optional): Text search queryfrom(optional): Filter by sender email addressto(optional): Filter by recipient email addresssubject(optional): Filter by subject textinMailbox(optional): Search within specific mailboxhasKeyword(optional): Filter by keyword (e.g., '$seen', '$flagged')notKeyword(optional): Exclude by keywordbefore(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 mailboxlimit(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 withnameandemailcc(optional): Array of CC recipientsbcc(optional): Array of BCC recipientssubject: Email subjecttextBody(optional): Plain text bodyhtmlBody(optional): HTML bodyidentityId(optional): Identity to send from
reply_to_email
Reply to an existing email.
Parameters:
emailId: ID of email to reply toreplyAll(optional): Reply to all recipients (default: false)subject(optional): Custom reply subjecttextBody(optional): Plain text bodyhtmlBody(optional): HTML bodyidentityId(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
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: 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
- Fork the repository
- Create a feature branch
- Make changes following the functional programming style
- Test your changes thoroughly
- 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