JMAP MCP Server
wyattjoh/jmap-mcp
Integração JMAP com MCP para gerenciamento total de email
Ver no GitHubServidor MCP para interagir com servidores de email compatíveis com JMAP (JSON Meta Application Protocol). Oferece ferramentas completas para buscar, gerenciar, sincronizar e compor emails, com suporte a threads, sincronização incremental e sincronização de buscas.
Instalação
npx convez-ai wyattjoh/jmap-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar buscas e filtros de email via API JMAP
- Sincronizar incrementalmente mudanças em emails e caixas postais
- Compor, responder e gerenciar emails programaticamente
- Integrar gerenciamento de email em agentes e workflows
Veredito

Excelente servidor MCP para quem trabalha com email em workflows automatizados. Implementação robusta com validação Zod, suporte a JMAP completo (RFC 8620/8621) e integração direta com FastMail e outros servidores compatíveis. Requer experiência com Deno e configuração de credenciais JMAP.
README
A tradução para o português deste README ainda está na fila.
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. 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 between mailboxes
- 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
Installation
Claude Code Plugin (Recommended)
Install via the plugin marketplace:
/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace
Then configure the required environment variables in your MCP server settings.
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": {
"jmap": {
"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.6.4"
],
"env": {
"JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
"JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
Replace
api.fastmail.comin--allow-netwith 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 IDlimit(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 fieldsbody(optional): Search in message body onlyfrom(optional): Filter by sender email addressto(optional): Filter by recipient email addresssubject(optional): Filter by subject textinMailbox(optional): Mailbox ID to search within (get fromget_mailboxes)hasKeyword(optional): Filter by keyword (e.g.,$seen,$flagged)notKeyword(optional): Exclude by keyword (e.g.,$seen,$draft)allInThreadHaveKeyword(optional): All emails in thread must have keywordsomeInThreadHaveKeyword(optional): At least one email in thread must have keywordbefore(optional): Only emails before date (ISO 8601 datetime)after(optional): Only emails after date (ISO 8601 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. Use properties to request only what you
need — fetching all properties returns large payloads.
Parameters:
ids: Array of email IDs (1-50 IDs)properties(optional): Specific properties to return. Recommended sets:- Summary:
["id", "subject", "from", "to", "receivedAt", "preview"] - Full read:
["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"] - Note: To get body content, include
bodyValuesANDtextBody/htmlBody
- Summary:
get_threads
Get email threads by their IDs. Thread IDs come from get_emails responses
(threadId property). Returns email IDs per thread — use get_emails on those
IDs to fetch content.
Parameters:
ids: Array of thread IDs (1-20 IDs)
get_email_changes
Get IDs of emails created, updated, or destroyed since a previous state. Use the
state string from a get_emails response.
Parameters:
sinceState: State string from a previousget_emailsresponsemaxChanges(optional): Max changes to return (1-500)fetchEmails(optional): Auto-fetch full email details for changed IDs (default: false)properties(optional): Properties to fetch whenfetchEmailsis true
get_search_updates
Get changes within a previous search query since its queryState. Must use the
same filter parameters as the original search_emails call.
Parameters:
sinceQueryState:queryStatefrom a previoussearch_emailsresponse- All filter parameters from
search_emails(must match original query) maxChanges(optional): Max changes to return (1-500)
mark_emails
Mark emails as read/unread or 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. Use get_mailboxes to find the target
mailbox ID.
Parameters:
ids: Array of email IDs (1-100 IDs)mailboxId: Target mailbox ID (get fromget_mailboxes)
delete_emails
Delete emails permanently (cannot be undone). Prefer moving to Trash via
move_emails for recoverable deletion.
Parameters:
ids: Array of email IDs (1-100 IDs)
send_email
Send a new email. Requires either textBody or htmlBody (or both).
Parameters:
to: Array of recipients (nameoptional,emailrequired)cc(optional): Array of CC recipientsbcc(optional): Array of BCC recipientssubject: Email subjecttextBody(optional): Plain text bodyhtmlBody(optional): HTML bodyidentityId(optional): JMAP identity ID to send from (uses server default if omitted)
reply_to_email
Reply to an existing email. Automatically sets To/CC, Re: subject prefix, and threading headers (In-Reply-To, References).
Parameters:
emailId: ID of email to reply toreplyAll(optional): Include all original recipients (default: false)subject(optional): Custom reply subject (defaults toRe: <original>)textBody(optional): Plain text bodyhtmlBody(optional): HTML bodyidentityId(optional): JMAP identity ID to send from (uses server default if omitted)
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
just watch # Run with file watching
just start # Run without watching
Testing
just test # Run all tests
just check # Format check + lint + type check
just fmt # Auto-format code
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