JMAP MCP Server

1# JMAP MCP Server
2 
3[![JSR](https://jsr.io/badges/@wyattjoh/jmap-mcp)](https://jsr.io/@wyattjoh/jmap-mcp)
4[![JSR Score](https://jsr.io/badges/@wyattjoh/jmap-mcp/score)](https://jsr.io/@wyattjoh/jmap-mcp)
5[![JSR Scope](https://jsr.io/badges/@wyattjoh)](https://jsr.io/@wyattjoh)
6 
7A Model Context Protocol (MCP) server that provides tools for interacting with
8JMAP (JSON Meta Application Protocol) email servers. Built with Deno and using
9the [@htunnicliff/jmap-jam](https://jsr.io/@htunnicliff/jmap-jam) client
10library.
11 
12## Features
13 
14### Email Management Tools
15 
16- **Search Emails**: Search emails with text queries, sender/recipient filters,
17  date ranges, and keywords
18- **Get Emails**: Retrieve specific emails by ID with full details
19- **Get Threads**: Retrieve email threads (conversation chains)
20- **Mark Emails**: Mark emails as read/unread, flagged/unflagged
21- **Move Emails**: Move emails between mailboxes
22- **Delete Emails**: Delete emails permanently
23 
24### Mailbox Management
25 
26- **Get Mailboxes**: List all mailboxes/folders with hierarchy support
27 
28### Email Composition
29 
30- **Send Email**: Compose and send new emails with support for plain text and
31  HTML
32- **Reply to Email**: Reply to existing emails with reply-all support
33 
34### Key Capabilities
35 
36- Full JMAP RFC 8620/8621 compliance via jmap-jam
37- Comprehensive input validation with Zod schemas
38- Pagination support for all list operations
39- Rich error handling and connection management
40- Functional programming patterns throughout
41- TypeScript support with strong typing
42 
43## Installation
44 
45### Prerequisites
46 
47- [Deno](https://deno.land/) v1.40 or later
48- A JMAP-compliant email server (e.g., Cyrus IMAP, Stalwart Mail Server,
49  FastMail)
50- Valid JMAP authentication credentials
51 
52### Setup
53 
54Add the following to your agent of choice:
55 
56```json
57{
58  "mcpServers": {
59    "fastmail": {
60      "type": "stdio",
61      "command": "deno",
62      "args": [
63        "run",
64        "--allow-net=api.fastmail.com",
65        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
66        "jsr:@wyattjoh/jmap-mcp@0.1.1"
67      ],
68      "env": {
69        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
70        "JMAP_BEARER_TOKEN": "API_TOKEN"
71      }
72    }
73  }
74}
75```
76 
77## Usage
78 
79### Environment Variables
80 
81| Variable            | Required | Description                                                     |
82| ------------------- | -------- | --------------------------------------------------------------- |
83| `JMAP_SESSION_URL`  | Yes      | JMAP server session URL (usually ends with `/.well-known/jmap`) |
84| `JMAP_BEARER_TOKEN` | Yes      | Bearer token for authentication                                 |
85| `JMAP_ACCOUNT_ID`   | No       | Account ID (auto-detected if not provided)                      |
86 
87### Available Tools
88 
89#### `search_emails`
90 
91Search for emails with various filters.
92 
93**Parameters:**
94 
95- `query` (optional): Text search query
96- `from` (optional): Filter by sender email address
97- `to` (optional): Filter by recipient email address
98- `subject` (optional): Filter by subject text
99- `inMailbox` (optional): Search within specific mailbox
100- `hasKeyword` (optional): Filter by keyword (e.g., '$seen', '$flagged')
101- `notKeyword` (optional): Exclude by keyword
102- `before` (optional): Only emails before date (ISO datetime)
103- `after` (optional): Only emails after date (ISO datetime)
104- `limit` (optional): Max results (1-100, default: 50)
105- `position` (optional): Starting position for pagination (default: 0)
106 
107#### `get_emails`
108 
109Retrieve specific emails by their IDs.
110 
111**Parameters:**
112 
113- `ids`: Array of email IDs (1-50 IDs)
114- `properties` (optional): Specific properties to return
115 
116#### `get_mailboxes`
117 
118Get list of mailboxes/folders.
119 
120**Parameters:**
121 
122- `parentId` (optional): Filter by parent mailbox
123- `limit` (optional): Max results (1-200, default: 100)
124- `position` (optional): Starting position for pagination
125 
126#### `get_threads`
127 
128Get email threads by their IDs.
129 
130**Parameters:**
131 
132- `ids`: Array of thread IDs (1-20 IDs)
133 
134#### `mark_emails`
135 
136Mark emails with keywords (read/unread, flagged/unflagged).
137 
138**Parameters:**
139 
140- `ids`: Array of email IDs (1-100 IDs)
141- `seen` (optional): Mark as read (true) or unread (false)
142- `flagged` (optional): Mark as flagged (true) or unflagged (false)
143 
144#### `move_emails`
145 
146Move emails to a different mailbox.
147 
148**Parameters:**
149 
150- `ids`: Array of email IDs (1-100 IDs)
151- `mailboxId`: Target mailbox ID
152 
153#### `delete_emails`
154 
155Delete emails permanently.
156 
157**Parameters:**
158 
159- `ids`: Array of email IDs (1-100 IDs)
160 
161#### `send_email`
162 
163Send a new email.
164 
165**Parameters:**
166 
167- `to`: Array of recipients with `name` and `email`
168- `cc` (optional): Array of CC recipients
169- `bcc` (optional): Array of BCC recipients
170- `subject`: Email subject
171- `textBody` (optional): Plain text body
172- `htmlBody` (optional): HTML body
173- `identityId` (optional): Identity to send from
174 
175#### `reply_to_email`
176 
177Reply to an existing email.
178 
179**Parameters:**
180 
181- `emailId`: ID of email to reply to
182- `replyAll` (optional): Reply to all recipients (default: false)
183- `subject` (optional): Custom reply subject
184- `textBody` (optional): Plain text body
185- `htmlBody` (optional): HTML body
186- `identityId` (optional): Identity to send from
187 
188## JMAP Server Compatibility
189 
190This server should work with any JMAP-compliant email server, including:
191 
192- [Cyrus IMAP](https://www.cyrusimap.org/) 3.0+
193- [Stalwart Mail Server](https://stalw.art/)
194- [FastMail](https://www.fastmail.com/) (commercial)
195- [Apache James](https://james.apache.org/) (with JMAP support)
196 
197## Development
198 
199### Running in Development
200 
201```bash
202deno run --allow-env --allow-net --watch src/mod.ts
203```
204 
205### Testing
206 
207```bash
208# Test connection
209deno run --allow-env --allow-net src/mod.ts
210```
211 
212## Architecture
213 
214The server is built using:
215 
216- **[Deno](https://deno.land/)**: Modern JavaScript/TypeScript runtime
217- **[@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)**:
218  MCP server framework
219- **[jmap-jam](https://jsr.io/@htunnicliff/jmap-jam)**: Lightweight, typed JMAP
220  client
221- **[Zod](https://zod.dev/)**: Runtime type validation
222 
223## Security
224 
225- All input is validated using Zod schemas
226- Environment variables are used for sensitive configuration
227- No secrets are logged or exposed in responses
228- Follows JMAP security best practices
229 
230## Contributing
231 
2321. Fork the repository
2332. Create a feature branch
2343. Make changes following the functional programming style
2354. Test your changes thoroughly
2365. Submit a pull request
237 
238## License
239 
240MIT License - see [LICENSE](LICENSE) file for details.
241 
242## Related Projects
243 
244- [jmap-jam](https://github.com/htunnicliff/jmap-jam) - JMAP client library
245- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
246- [JMAP RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) - JMAP core
247  protocol
248- [JMAP RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621) - JMAP for Mail
249