Skip to content
Back to search

jmap-mcp

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 jmap-jam client library.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wyattjoh--jmap-mcp/badge.svg)](/listings/wyattjoh--jmap-mcp)

HTML

<a href="/listings/wyattjoh--jmap-mcp"><img src="/api/listings/wyattjoh--jmap-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://deno.land/) 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:

{
  "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.5"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

> Replace `api.fastmail.com` in `--allow-net` with your JMAP server's hostname > if not using FastMail.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 44 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "jmap-mcp",
  3. "version": "0.6.5",
  4. "description": "MCP server for JMAP email management",
  5. "author": {
  6. "name": "Wyatt Johnson"
  7. },
  8. "userConfig": {
  9. "jmap_session_url": {
  10. "title": "JMAP Session URL",
  11. "type": "string",
  12. "description": "JMAP server session URL (e.g., https://api.fastmail.com/jmap/session)",
  13. "sensitive": false
  14. },
  15. "jmap_bearer_token": {
  16. "title": "JMAP Bearer Token",
  17. "type": "string",
  18. "description": "Bearer token for JMAP authentication",
  19. "sensitive": true
  20. },
  21. "jmap_account_id": {
  22. "title": "JMAP Account ID",
  23. "type": "string",
  24. "description": "JMAP account ID (optional, auto-detected if not provided)",
  25. "sensitive": false
  26. }
  27. },
  28. "mcpServers": {
  29. "jmap": {
  30. "command": "deno",
  31. "args": [
  32. "run",
  33. "--allow-env",
  34. "--allow-net",
  35. "jsr:@wyattjoh/jmap-mcp@0.6.5"
  36. ],
  37. "env": {
  38. "JMAP_SESSION_URL": "${user_config.jmap_session_url}",
  39. "JMAP_BEARER_TOKEN": "${user_config.jmap_bearer_token}",
  40. "JMAP_ACCOUNT_ID": "${user_config.jmap_account_id}"
  41. }
  42. }
  43. }
  44. }
README.md · README · 368 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # JMAP MCP Server
  2. [![JSR](https://jsr.io/badges/@wyattjoh/jmap-mcp)](https://jsr.io/@wyattjoh/jmap-mcp)
  3. [![JSR Score](https://jsr.io/badges/@wyattjoh/jmap-mcp/score)](https://jsr.io/@wyattjoh/jmap-mcp)
  4. [![JMAP Client](https://jsr.io/badges/@wyattjoh/jmap)](https://jsr.io/@wyattjoh/jmap)
  5. [![JSR Scope](https://jsr.io/badges/@wyattjoh)](https://jsr.io/@wyattjoh)
  6. A Deno workspace containing a functional JMAP email client and a Model Context
  7. Protocol (MCP) server built on top of it. The client package uses
  8. [jmap-jam](https://github.com/htunnicliff/jmap-jam) for JMAP protocol access;
  9. the MCP package adapts those typed operations into tools.
  10. ## Features
  11. ### Email Management Tools
  12. - **Search Emails**: Search emails with text queries, sender/recipient filters,
  13. date ranges, and keywords. All filters are AND'd together.
  14. - **Get Emails**: Retrieve specific emails by ID with configurable property
  15. selection
  16. - **Get Threads**: Retrieve email threads (conversation chains)
  17. - **Mark Emails**: Mark emails as read/unread, flagged/unflagged
  18. - **Move Emails**: Move emails to one mailbox
  19. - **Patch Email Mailboxes**: Add or remove selected mailbox memberships while
  20. preserving unspecified memberships
  21. - **Delete Emails**: Delete emails permanently
  22. ### Mailbox Management
  23. - **Get Mailboxes**: List all mailboxes/folders with hierarchy support. Use this
  24. to find mailbox IDs needed by other tools.
  25. ### Incremental Sync
  26. - **Get Email Changes**: Get IDs of emails created, updated, or destroyed since
  27. a previous state (state-based delta tracking)
  28. - **Get Search Updates**: Get additions/removals within a previous search query
  29. since its last queryState
  30. ### Email Composition
  31. - **Send Email**: Compose and send new emails with support for plain text and
  32. HTML
  33. - **Reply to Email**: Reply to existing emails with automatic header handling
  34. and reply-all support
  35. ### Key Capabilities
  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. - State-based incremental sync for efficient polling
  40. - Rich error handling and connection management
  41. - Capability-based tool registration (read-only, submission)
  42. - TypeScript support with strong typing
  43. ### Reusable JMAP Client
  44. Standalone applications can import `@wyattjoh/jmap` without creating an MCP
  45. server or transport:
  46. ```ts
  47. import { connectJmap, searchEmails } from "jsr:@wyattjoh/jmap";
  48. const connection = await connectJmap({
  49. sessionUrl: Deno.env.get("JMAP_SESSION_URL")!,
  50. bearerToken: Deno.env.get("JMAP_BEARER_TOKEN")!,
  51. accountId: Deno.env.get("JMAP_ACCOUNT_ID"),
  52. });
  53. const unread = await searchEmails(connection, {
  54. filter: { inMailbox: "inbox-id", notKeyword: "$seen" },
  55. limit: 50,
  56. position: 0,
  57. });
  58. ```
  59. See [`packages/jmap/README.md`](packages/jmap/README.md) for the client package.
  60. ## Installation
  61. ### Claude Code Plugin (Recommended)
  62. Install via the plugin marketplace:
  63. ```shell
  64. /plugin marketplace add wyattjoh/claude-code-marketplace
  65. /plugin install jmap-mcp@wyattjoh-marketplace
  66. ```
  67. Then configure the required environment variables in your MCP server settings.
  68. ### Prerequisites
  69. - [Deno](https://deno.land/) v2 or later
  70. - A JMAP-compliant email server (e.g., Cyrus IMAP, Stalwart Mail Server,
  71. FastMail)
  72. - Valid JMAP authentication credentials
  73. ### Setup
  74. Add the following to your agent of choice:
  75. <!-- x-release-please-start-version -->
  76. ```json
  77. {
  78. "mcpServers": {
  79. "jmap": {
  80. "type": "stdio",
  81. "command": "deno",
  82. "args": [
  83. "run",
  84. "--allow-net=api.fastmail.com",
  85. "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
  86. "jsr:@wyattjoh/jmap-mcp@0.6.5"
  87. ],
  88. "env": {
  89. "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
  90. "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. <!-- x-release-please-end -->
  97. > Replace `api.fastmail.com` in `--allow-net` with your JMAP server's hostname
  98. > if not using FastMail.
  99. ## Usage
  100. ### Environment Variables
  101. | Variable | Required | Description |
  102. | ------------------- | -------- | --------------------------------------------------------------- |
  103. | `JMAP_SESSION_URL` | Yes | JMAP server session URL (usually ends with `/.well-known/jmap`) |
  104. | `JMAP_BEARER_TOKEN` | Yes | Bearer token for authentication |
  105. | `JMAP_ACCOUNT_ID` | No | Account ID (auto-detected if not provided) |
  106. ### Available Tools
  107. #### `get_mailboxes`
  108. List mailboxes/folders with their IDs, names, and metadata. **Call this first**
  109. to get mailbox IDs needed by `search_emails` (`inMailbox`) and `move_emails`
  110. (`mailboxId`). Common names: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.
  111. **Parameters:**
  112. - `parentId` (optional): Filter by parent mailbox ID
  113. - `limit` (optional): Max results (1-200, default: 100)
  114. - `position` (optional): Starting position for pagination
  115. #### `search_emails`
  116. Search emails with filters. **All filters are AND'd together.** Returns only
  117. email IDs — use `get_emails` to fetch content. Results include `queryState` for
  118. incremental sync via `get_search_updates`.
  119. **Parameters:**
  120. - `query` (optional): Text search across all fields
  121. - `body` (optional): Search in message body only
  122. - `from` (optional): Filter by sender email address
  123. - `to` (optional): Filter by recipient email address
  124. - `subject` (optional): Filter by subject text
  125. - `inMailbox` (optional): Mailbox ID to search within (get from `get_mailboxes`)
  126. - `hasKeyword` (optional): Filter by keyword (e.g., `$seen`, `$flagged`)
  127. - `notKeyword` (optional): Exclude by keyword (e.g., `$seen`, `$draft`)
  128. - `allInThreadHaveKeyword` (optional): All emails in thread must have keyword
  129. - `someInThreadHaveKeyword` (optional): At least one email in thread must have
  130. keyword
  131. - `before` (optional): Only emails before date (ISO 8601 datetime)
  132. - `after` (optional): Only emails after date (ISO 8601 datetime)
  133. - `limit` (optional): Max results (1-100, default: 50)
  134. - `position` (optional): Starting position for pagination (default: 0)
  135. #### `get_emails`
  136. Retrieve specific emails by their IDs. Use `properties` to request only what you
  137. need — fetching all properties returns large payloads.
  138. **Parameters:**
  139. - `ids`: Array of email IDs (1-50 IDs)
  140. - `properties` (optional): Specific properties to return. Recommended sets:
  141. - Summary: `["id", "subject", "from", "to", "receivedAt", "preview"]`
  142. - Full read:
  143. `["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]`
  144. - **Note:** To get body content, include `bodyValues` AND
  145. `textBody`/`htmlBody`
  146. #### `get_threads`
  147. Get email threads by their IDs. Thread IDs come from `get_emails` responses
  148. (`threadId` property). Returns email IDs per thread — use `get_emails` on those
  149. IDs to fetch content.
  150. **Parameters:**
  151. - `ids`: Array of thread IDs (1-20 IDs)
  152. #### `get_email_changes`
  153. Get IDs of emails created, updated, or destroyed since a previous state. Use the
  154. `state` string from a `get_emails` response.
  155. **Parameters:**
  156. - `sinceState`: State string from a previous `get_emails` response
  157. - `maxChanges` (optional): Max changes to return (1-500)
  158. - `fetchEmails` (optional): Auto-fetch full email details for changed IDs
  159. (default: false)
  160. - `properties` (optional): Properties to fetch when `fetchEmails` is true
  161. #### `get_search_updates`
  162. Get changes within a previous search query since its `queryState`. Must use the
  163. same filter parameters as the original `search_emails` call.
  164. **Parameters:**
  165. - `sinceQueryState`: `queryState` from a previous `search_emails` response
  166. - All filter parameters from `search_emails` (must match original query)
  167. - `maxChanges` (optional): Max changes to return (1-500)
  168. #### `mark_emails`
  169. Mark emails as read/unread or flagged/unflagged.
  170. **Parameters:**
  171. - `ids`: Array of email IDs (1-100 IDs)
  172. - `seen` (optional): Mark as read (`true`) or unread (`false`)
  173. - `flagged` (optional): Mark as flagged (`true`) or unflagged (`false`)
  174. #### `move_emails`
  175. Move emails to a different mailbox. Use `get_mailboxes` to find the target
  176. mailbox ID.
  177. **Parameters:**
  178. - `ids`: Array of email IDs (1-100 IDs)
  179. - `mailboxId`: Target mailbox ID (get from `get_mailboxes`)
  180. #### `patch_email_mailboxes`
  181. Add or remove selected mailbox memberships without replacing unspecified
  182. memberships. This supports label-like workflows and compound categorization.
  183. **Parameters:**
  184. - `ids`: Array of email IDs (1-100 IDs)
  185. - `addMailboxIds` (optional): Mailbox IDs to add
  186. - `removeMailboxIds` (optional): Mailbox IDs to remove
  187. At least one mailbox must be added or removed. A mailbox cannot appear in both
  188. arrays.
  189. #### `delete_emails`
  190. Delete emails permanently (cannot be undone). Prefer moving to Trash via
  191. `move_emails` for recoverable deletion.
  192. **Parameters:**
  193. - `ids`: Array of email IDs (1-100 IDs)
  194. #### `send_email`
  195. Send a new email. Requires either `textBody` or `htmlBody` (or both).
  196. **Parameters:**
  197. - `to`: Array of recipients (`name` optional, `email` required)
  198. - `cc` (optional): Array of CC recipients
  199. - `bcc` (optional): Array of BCC recipients
  200. - `subject`: Email subject
  201. - `textBody` (optional): Plain text body
  202. - `htmlBody` (optional): HTML body
  203. - `identityId` (optional): JMAP identity ID to send from (uses server default if
  204. omitted)
  205. #### `reply_to_email`
  206. Reply to an existing email. Automatically sets To/CC, Re: subject prefix, and
  207. threading headers (In-Reply-To, References).
  208. **Parameters:**
  209. - `emailId`: ID of email to reply to
  210. - `replyAll` (optional): Include all original recipients (default: false)
  211. - `subject` (optional): Custom reply subject (defaults to `Re: <original>`)
  212. - `textBody` (optional): Plain text body
  213. - `htmlBody` (optional): HTML body
  214. - `identityId` (optional): JMAP identity ID to send from (uses server default if
  215. omitted)
  216. ## JMAP Server Compatibility
  217. This server should work with any JMAP-compliant email server, including:
  218. - [Cyrus IMAP](https://www.cyrusimap.org/) 3.0+
  219. - [Stalwart Mail Server](https://stalw.art/)
  220. - [FastMail](https://www.fastmail.com/) (commercial)
  221. - [Apache James](https://james.apache.org/) (with JMAP support)
  222. ## Development
  223. ### Running in Development
  224. ```bash
  225. deno task watch # Run with file watching
  226. deno task start # Run without watching
  227. ```
  228. ### Testing
  229. ```bash
  230. deno task test # Run all tests
  231. deno task check # Type-check both packages
  232. deno task lint # Lint workspace packages
  233. deno task fmt # Format code
  234. deno task publish:check # Validate both JSR packages
  235. ```
  236. ## Architecture
  237. The repository is a Deno workspace with two independently publishable packages:
  238. - **`packages/jmap` / `@wyattjoh/jmap`**: Functional connection, retrieval,
  239. incremental sync, mutation, and submission operations
  240. - **`packages/jmap-mcp` / `@wyattjoh/jmap-mcp`**: MCP schemas, tool adapters,
  241. capability registration, and stdio entrypoint
  242. The MCP adapters call the client package directly. JMAP behavior belongs in the
  243. client package; transport validation and user-facing tool contracts belong in
  244. the MCP package.
  245. ## Security
  246. - All input is validated using Zod schemas
  247. - Environment variables are used for sensitive configuration
  248. - No secrets are logged or exposed in responses
  249. - Follows JMAP security best practices
  250. ## Contributing
  251. 1. Fork the repository
  252. 2. Create a feature branch
  253. 3. Make changes following the functional programming style
  254. 4. Test your changes thoroughly
  255. 5. Submit a pull request
  256. ## License
  257. MIT License - see [LICENSE](LICENSE) file for details.
  258. ## Related Projects
  259. - [jmap-jam](https://github.com/htunnicliff/jmap-jam) - JMAP client library
  260. - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
  261. - [JMAP RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) - JMAP core
  262. protocol
  263. - [JMAP RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621) - JMAP for Mail

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.