Che Apple Mail MCP

Apple Mail MCP — 44 tools, SQLite millisecond search, .emlx parser, batch ops

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Remote HTTP

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "che-apple-mail-mcp": {
      "url": "https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT"
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

che-apple-mail-mcp

The most comprehensive Apple Mail MCP server - 53 tools with SQLite-powered millisecond search across 250K+ emails.

English | 繁體中文

Why che-apple-mail-mcp?

Feature	Other MCPs	che-apple-mail-mcp
Total Tools	~20	53
Language	Python	Swift (Native)
Search Speed	Seconds (AppleScript)	Milliseconds (SQLite)
Search Fields	Subject/Sender	Subject/Sender/Recipient/Date
Batch Operations	No	Up to 50 emails per call
Mailbox Management	Basic	Full CRUD
Email Colors	No	7 flag colors + background
VIP Management	No	Yes
Rule Management	Partial	Full CRUD
Signatures	No	Yes
Raw Headers/Source	No	Yes

Quick Start

Install the plugin. It brings the signed binary, the /archive-mail command family, the safety rules, and the staleness hook as one unit:

Terminal

claude plugin marketplace add PsychQuant/che-apple-mail-mcp
claude plugin install che-apple-mail-mcp@che-apple-mail-mcp

Then grant permissions — the setup window shows live status and links straight to the right System Settings pane:

bash

~/bin/CheAppleMailMCP --setup

💡 Full Disk Access is what makes the fast SQLite read path and batch_export_emails_markdown work. Without it the tools still run but read little or nothing, which is easy to mistake for a bug rather than a permission. macOS does not let an app request FDA programmatically — it has to be ticked by hand — which is exactly what the setup window is there to make quick.

Plugin vs MCP-only

Registering the MCP server by itself is a supported advanced path, but it is a strictly smaller install. Choose it knowingly — nothing at runtime will tell you these are missing (#353):

Shipped by the plugin	Present with MCP-only
All 53 MCP tools	✅ yes
`/archive-mail` + `-migrate` / `-rebuild-threads` / `-repair-synthetic-ids` / `-view`	❌ the archiving SOP does not exist
`rules/compose-wrapper-free.md` — what the cite-block was, and what a refused compose call means	⚠️ background: since #304 the wrapper is structurally impossible, so this rule now explains the six refusal reasons and their recipes rather than guarding against a silent fallback
`rules/confirmation-triggers.md`, `rules/false-positive-detection.md`	❌ no confirmation discipline on destructive operations
`hooks/session-start.sh` — staleness kill	❌ a session can keep running a stale binary after an upgrade
Developer ID signed + notarized binary	❌ a self-built binary is ad-hoc signed; on macOS 26 TCC cannot reliably hold FDA/Automation for it, so permissions appear to be granted and then stop working (#211)
Version sidecar → `--self-update` + the #303 staleness self-check	❌ no sidecar next to a hand-built binary, so that check is permanently silent

Advanced: register the MCP server only (development, or you want no plugin)

bash

git clone https://github.com/PsychQuant/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

# --scope user     : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --               : separator between claude options and the command
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Install the binary to a local directory like ~/bin/. Avoid cloud-synced folders (Dropbox, iCloud, OneDrive) — sync activity causes MCP connection timeouts.

For a self-built binary to hold TCC permissions across rebuilds, sign it with a Developer ID; see Signing & Notarization. Otherwise expect to re-grant permissions after every build.

Recent Releases

For full details see CHANGELOG.md.

v2.7.2 (2026-05-10) — `attachmentFragment` cluster + fallback parity

Hardened attachmentFragment indent across all 3 callers + removed dead MailController.attachmentScript helper that bypassed v2.7.0's race-mitigation delays (#61, #62)
Attachment count cap (50) + env-configurable delays via CHE_MAIL_ATTACHMENT_DELAY_BETWEEN / _TRAILING (#63, #64)
get_email_metadata SQLite path now falls back to AppleScript on error — last read-tool gap closed; all 8 SQLite-first read tools now have parity fallback (#71)

v2.7.1 (2026-05-09) — base64 fix + `.partial.emlx` + observability

Critical: RFC822 header/body split was returning a relative array index instead of an absolute Data index, causing html_body to begin with "sion: 1.0\n\n<base64>" for some Android Gmail messages — raw base64 leaked into LLM context and triggered AUP false-positives downstream (#72)
save_attachment now reads from Attachments/<rowId>/<part_id>/<filename> cache when .partial.emlx body is empty — no more silent 0-byte writes for IMAP messages with stripped binaries (#66)
SQLite fast-path failures now log to stderr (SQLite ... fast path failed for rowId=...; falling through to AppleScript) (#69)

v2.7.0 (2026-05-04) — Mail.app race mitigation

Multi-attachment AppleScript paced with 0.3s between + 0.5s trailing delays to mitigate Mail.app silently dropping attachments under fast IPC (#60)

v2.6.0 (2026-05-03) — Security & validation hardening (8 PRs, 16 issues)

forward_email plain mode now embeds RFC 3676 > quoted original (parity with reply_email's #43 fix) (#44)
Hard-fail on tool param type mismatch — bool / [String] no longer silently coerced (#35)
Recipient email validation rejects header injection (control chars, missing/multiple @) (#41)
cc_additional deduplicates case-insensitively (#34)
Attachment path deny-list (~/.ssh, Keychains, TCC db, browser cookies) + symlink-resolved + new MAIL_MCP_ATTACHMENT_ROOTS env allow-list (#38)
All 17 id-taking tools hard-validate id as Int at handler boundary — defeats AppleScript predicate injection (#50)
Gated integration tests for reply_email runtime (#37, #45) + smoke matrix templates (#46, #47)

v2.5.0 (2026-04-17) — Composing `format` parameter

All 4 composing tools (compose_email / create_draft / reply_email / forward_email) gain format: "plain" | "markdown" | "html" param (closes #14, #15)
New message-composition capability spec

All 53 Tools

Accounts (2)

Tool	Description
`list_accounts`	List all mail accounts
`get_account_info`	Get account details

Mailboxes (4)

Tool	Description
`list_mailboxes`	List all mailboxes (folders)
`create_mailbox`	Create a new mailbox
`delete_mailbox`	Delete a mailbox
`get_special_mailboxes`	Get special mailbox names (inbox, drafts, sent, trash, junk, outbox)

Emails (7)

Tool	Description
`list_emails`	List emails in a mailbox
`get_email`	Get full email content
`search_emails`	Search by subject/content
`get_unread_count`	Get unread count
`get_email_headers`	Get all email headers
`get_email_source`	Get raw email source
`get_email_metadata`	Get metadata (forwarded, replied, size)

Actions (8)

Tool	Description
`mark_read`	Mark as read/unread
`flag_email`	Flag/unflag email
`set_flag_color`	Set flag color (7 colors)
`set_background_color`	Set email background color
`mark_as_junk`	Mark as junk/not junk
`move_email`	Move to another mailbox
`copy_email`	Copy to another mailbox
`delete_email`	Delete email (to trash)

Compose (5)

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Che Apple Mail MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "che-apple-mail-mcp": { "command": "npx", "args": ["-y", "che-apple-mail-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Che Apple Mail MCP AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/che-apple-mail-mcp?style=directory)](https://allmcps.com/mcp/che-apple-mail-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/che-apple-mail-mcp"><img src="https://allmcps.com/api/badge/che-apple-mail-mcp?style=directory" alt="Che Apple Mail MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

37Quality signal: Fair · 37/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools15/30

Adoption & activity3/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Che Apple Mail MCP →Install in Claude Desktop Install in Cursor Install in VS Code

Che Apple Mail MCP

Apple Mail MCP — 44 tools, SQLite millisecond search, .emlx parser, batch ops

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Remote HTTP

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "che-apple-mail-mcp": {
      "url": "https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT"
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

che-apple-mail-mcp

The most comprehensive Apple Mail MCP server - 53 tools with SQLite-powered millisecond search across 250K+ emails.

English | 繁體中文

Why che-apple-mail-mcp?

Feature	Other MCPs	che-apple-mail-mcp
Total Tools	~20	53
Language	Python	Swift (Native)
Search Speed	Seconds (AppleScript)	Milliseconds (SQLite)
Search Fields	Subject/Sender	Subject/Sender/Recipient/Date
Batch Operations	No	Up to 50 emails per call
Mailbox Management	Basic	Full CRUD
Email Colors	No	7 flag colors + background
VIP Management	No	Yes
Rule Management	Partial	Full CRUD
Signatures	No	Yes
Raw Headers/Source	No	Yes

Quick Start

Install the plugin. It brings the signed binary, the /archive-mail command family, the safety rules, and the staleness hook as one unit:

Terminal

claude plugin marketplace add PsychQuant/che-apple-mail-mcp
claude plugin install che-apple-mail-mcp@che-apple-mail-mcp

Then grant permissions — the setup window shows live status and links straight to the right System Settings pane:

bash

~/bin/CheAppleMailMCP --setup

💡 Full Disk Access is what makes the fast SQLite read path and batch_export_emails_markdown work. Without it the tools still run but read little or nothing, which is easy to mistake for a bug rather than a permission. macOS does not let an app request FDA programmatically — it has to be ticked by hand — which is exactly what the setup window is there to make quick.

Plugin vs MCP-only

Registering the MCP server by itself is a supported advanced path, but it is a strictly smaller install. Choose it knowingly — nothing at runtime will tell you these are missing (#353):

Shipped by the plugin	Present with MCP-only
All 53 MCP tools	✅ yes
`/archive-mail` + `-migrate` / `-rebuild-threads` / `-repair-synthetic-ids` / `-view`	❌ the archiving SOP does not exist
`rules/compose-wrapper-free.md` — what the cite-block was, and what a refused compose call means	⚠️ background: since #304 the wrapper is structurally impossible, so this rule now explains the six refusal reasons and their recipes rather than guarding against a silent fallback
`rules/confirmation-triggers.md`, `rules/false-positive-detection.md`	❌ no confirmation discipline on destructive operations
`hooks/session-start.sh` — staleness kill	❌ a session can keep running a stale binary after an upgrade
Developer ID signed + notarized binary	❌ a self-built binary is ad-hoc signed; on macOS 26 TCC cannot reliably hold FDA/Automation for it, so permissions appear to be granted and then stop working (#211)
Version sidecar → `--self-update` + the #303 staleness self-check	❌ no sidecar next to a hand-built binary, so that check is permanently silent

Advanced: register the MCP server only (development, or you want no plugin)

bash

git clone https://github.com/PsychQuant/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

# --scope user     : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --               : separator between claude options and the command
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Install the binary to a local directory like ~/bin/. Avoid cloud-synced folders (Dropbox, iCloud, OneDrive) — sync activity causes MCP connection timeouts.

For a self-built binary to hold TCC permissions across rebuilds, sign it with a Developer ID; see Signing & Notarization. Otherwise expect to re-grant permissions after every build.

Recent Releases

For full details see CHANGELOG.md.

v2.7.2 (2026-05-10) — `attachmentFragment` cluster + fallback parity

Hardened attachmentFragment indent across all 3 callers + removed dead MailController.attachmentScript helper that bypassed v2.7.0's race-mitigation delays (#61, #62)
Attachment count cap (50) + env-configurable delays via CHE_MAIL_ATTACHMENT_DELAY_BETWEEN / _TRAILING (#63, #64)
get_email_metadata SQLite path now falls back to AppleScript on error — last read-tool gap closed; all 8 SQLite-first read tools now have parity fallback (#71)

v2.7.1 (2026-05-09) — base64 fix + `.partial.emlx` + observability

Critical: RFC822 header/body split was returning a relative array index instead of an absolute Data index, causing html_body to begin with "sion: 1.0\n\n<base64>" for some Android Gmail messages — raw base64 leaked into LLM context and triggered AUP false-positives downstream (#72)
save_attachment now reads from Attachments/<rowId>/<part_id>/<filename> cache when .partial.emlx body is empty — no more silent 0-byte writes for IMAP messages with stripped binaries (#66)
SQLite fast-path failures now log to stderr (SQLite ... fast path failed for rowId=...; falling through to AppleScript) (#69)

v2.7.0 (2026-05-04) — Mail.app race mitigation

Multi-attachment AppleScript paced with 0.3s between + 0.5s trailing delays to mitigate Mail.app silently dropping attachments under fast IPC (#60)

v2.6.0 (2026-05-03) — Security & validation hardening (8 PRs, 16 issues)

forward_email plain mode now embeds RFC 3676 > quoted original (parity with reply_email's #43 fix) (#44)
Hard-fail on tool param type mismatch — bool / [String] no longer silently coerced (#35)
Recipient email validation rejects header injection (control chars, missing/multiple @) (#41)
cc_additional deduplicates case-insensitively (#34)
Attachment path deny-list (~/.ssh, Keychains, TCC db, browser cookies) + symlink-resolved + new MAIL_MCP_ATTACHMENT_ROOTS env allow-list (#38)
All 17 id-taking tools hard-validate id as Int at handler boundary — defeats AppleScript predicate injection (#50)
Gated integration tests for reply_email runtime (#37, #45) + smoke matrix templates (#46, #47)

v2.5.0 (2026-04-17) — Composing `format` parameter

All 4 composing tools (compose_email / create_draft / reply_email / forward_email) gain format: "plain" | "markdown" | "html" param (closes #14, #15)
New message-composition capability spec

All 53 Tools

Accounts (2)

Tool	Description
`list_accounts`	List all mail accounts
`get_account_info`	Get account details

Mailboxes (4)

Tool	Description
`list_mailboxes`	List all mailboxes (folders)
`create_mailbox`	Create a new mailbox
`delete_mailbox`	Delete a mailbox
`get_special_mailboxes`	Get special mailbox names (inbox, drafts, sent, trash, junk, outbox)

Emails (7)

Tool	Description
`list_emails`	List emails in a mailbox
`get_email`	Get full email content
`search_emails`	Search by subject/content
`get_unread_count`	Get unread count
`get_email_headers`	Get all email headers
`get_email_source`	Get raw email source
`get_email_metadata`	Get metadata (forwarded, replied, size)

Actions (8)

Tool	Description
`mark_read`	Mark as read/unread
`flag_email`	Flag/unflag email
`set_flag_color`	Set flag color (7 colors)
`set_background_color`	Set email background color
`mark_as_junk`	Mark as junk/not junk
`move_email`	Move to another mailbox
`copy_email`	Copy to another mailbox
`delete_email`	Delete email (to trash)

Compose (5)

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Che Apple Mail MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "che-apple-mail-mcp": { "command": "npx", "args": ["-y", "che-apple-mail-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/che-apple-mail-mcp?style=directory)](https://allmcps.com/mcp/che-apple-mail-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/che-apple-mail-mcp"><img src="https://allmcps.com/api/badge/che-apple-mail-mcp?style=directory" alt="Che Apple Mail MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

37Quality signal: Fair · 37/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools15/30

Adoption & activity3/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Che Apple Mail MCP →Install in Claude Desktop Install in Cursor Install in VS Code

Che Apple Mail MCP

Quick Install

Client Config & Setup

Documentation Overview

che-apple-mail-mcp

Why che-apple-mail-mcp?

Quick Start

Plugin vs MCP-only

Recent Releases

v2.7.2 (2026-05-10) — attachmentFragment cluster + fallback parity

v2.7.1 (2026-05-09) — base64 fix + .partial.emlx + observability

v2.7.0 (2026-05-04) — Mail.app race mitigation

v2.6.0 (2026-05-03) — Security & validation hardening (8 PRs, 16 issues)

v2.5.0 (2026-04-17) — Composing format parameter

All 53 Tools

Related MCP Servers

Reviews

Frequently Asked Questions about Che Apple Mail MCP

AllMCPs Directory Badge

Technical Specs & Signals

Moxie Docs MCP

Own this project?

Share & Embed

Explore more

Che Apple Mail MCP

Quick Install

Client Config & Setup

Documentation Overview

che-apple-mail-mcp

Why che-apple-mail-mcp?

Quick Start

Plugin vs MCP-only

Recent Releases

v2.7.2 (2026-05-10) — attachmentFragment cluster + fallback parity

v2.7.1 (2026-05-09) — base64 fix + .partial.emlx + observability

v2.7.0 (2026-05-04) — Mail.app race mitigation

v2.6.0 (2026-05-03) — Security & validation hardening (8 PRs, 16 issues)

v2.5.0 (2026-04-17) — Composing format parameter

All 53 Tools

Related MCP Servers

Reviews

Frequently Asked Questions about Che Apple Mail MCP

AllMCPs Directory Badge

Technical Specs & Signals

Moxie Docs MCP

Own this project?

Share & Embed

Explore more

v2.7.2 (2026-05-10) — `attachmentFragment` cluster + fallback parity

v2.7.1 (2026-05-09) — base64 fix + `.partial.emlx` + observability

v2.5.0 (2026-04-17) — Composing `format` parameter

v2.7.2 (2026-05-10) — `attachmentFragment` cluster + fallback parity

v2.7.1 (2026-05-09) — base64 fix + `.partial.emlx` + observability

v2.5.0 (2026-04-17) — Composing `format` parameter