wyattjoh/jmap-mcp

A Deno workspace containing a functional JMAP email client and a Model Context
Protocol (MCP) server built on top of it. The client package uses
jmap-jam for JMAP protocol access;
the MCP package adapts those typed operations into tools.
Features
Email Management Tools
- **Search Emails**: Search emails with text queries, sender/recipient filters,
date ranges, and keywords. All filters are AND'd together.
- **Get Emails**: Retrieve specific emails by ID with configurable property
selection
- **Get Threads**: Retrieve email threads (conversation chains)
- **Mark Emails**: Mark emails as read/unread, flagged/unflagged
- **Move Emails**: Move emails to one mailbox
- **Patch Email Mailboxes**: Add or remove selected mailbox memberships while
preserving unspecified memberships
- **Delete Emails**: Delete emails permanently
Mailbox Management
- **Get Mailboxes**: List all mailboxes/folders with hierarchy support. Use this
to find mailbox IDs needed by other tools.
Incremental Sync
- **Get Email Changes**: Get IDs of emails created, updated, or destroyed since
a previous state (state-based delta tracking)
- **Get Search Updates**: Get additions/removals within a previous search query
since its last queryState
Email Composition
- **Send Email**: Compose and send new emails with support for plain text and
HTML
- **Reply to Email**: Reply to existing emails with automatic header handling
and 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
- State-based incremental sync for efficient polling
- Rich error handling and connection management
- Capability-based tool registration (read-only, submission)
- TypeScript support with strong typing
Reusable JMAP Client
Standalone applications can import @wyattjoh/jmap without creating an MCP
server or transport:
See packages/jmap/README.md for the client package.
Installation
Claude Code Plugin (Recommended)
Install via the plugin marketplace:
Then configure the required environment variables in your MCP server settings.
Prerequisites
- Deno v2 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:
> Replace api.fastmail.com in --allow-net with your JMAP server's hostname
> if not using FastMail.
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
get_mailboxes
List mailboxes/folders with their IDs, names, and metadata. **Call this first**
to get mailbox IDs needed by search_emails (inMailbox) and move_emails
(mailboxId). Common names: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.
**Parameters:**
- parentId (optional): Filter by parent mailbox ID
- limit (optional): Max results (1-200, default: 100)
- position (optional): Starting position for pagination
search_emails
Search emails with filters. **All filters are AND'd together.** Returns only
email IDs — use get_emails to fetch content. Results include queryState for
incremental sync via get_search_updates.
**Parameters:**
- query (optional): Text search across all fields
- body (optional): Search in message body only
- from (optional): Filter by sender email address
- to (optional): Filter by recipient email address
- subject (optional): Filter by subject text