What is apple-mail-mcp CLAUDE.md?

Project instructions for an Apple Mail MCP server, which lets an AI assistant work with Apple Mail on macOS through AppleScript. It also explains optional IMAP and SMTP setup and safe handling of backslashes.

It helps configure mail accounts, use faster mailbox searching or counting through IMAP, send mail through SMTP, and correctly pass text containing backslashes.

It documents how mail access and account configuration work, including details that can otherwise cause failed commands or message problems.

How sweetrb/apple-mail-mcp configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to sweetrb/apple-mail-mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/sweetrb/apple-mail-mcp/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/sweetrb/apple-mail-mcp

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/sweetrb/apple-mail-mcp/claude-md/github.svg)](https://agentmods.dev/instructions/sweetrb/apple-mail-mcp/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/sweetrb/apple-mail-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/sweetrb/apple-mail-mcp/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/sweetrb/apple-mail-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/sweetrb/apple-mail-mcp/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 6,496 This file is loaded in full into every session.

When invoked 6,496 The same file — it is already loaded in full.

Security scan A 1 finding. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.06496	$0.06496
Opus 5.5	$0.02598	$0.02598
Sonnet 5.5	$0.01299	$0.01299
Haiku 4.5	$0.00650	$0.00650

Measured 10d ago against content hash 95ee2165fc6e, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

apple-mail-mcp CLAUDE.md scanned grade A with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 10d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Runs shell commandslowCapability

Expected in a hook, worth knowing in a rule or an instructions file.

Prior to v1.4.0, `reply-to-message` and `forward-message` would send replies/forwards with **empty body text** when the MCP server was running as a background process (e.g., spawned via `execSync` from a Node.js MCP serv

CLAUDE.md · 455 lines

How it starts

The opening of the file, as written. The whole thing — 455 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md - Apple Mail MCP Server

This file provides guidance for AI agents (Claude, etc.) when using this MCP server.

Overview

This MCP server enables AI assistants to interact with Apple Mail on macOS via AppleScript. All operations are local - no data leaves the user's machine.

Configuring IMAP / SMTP (when a user asks to set it up)

The AppleScript backend needs no config. The opt-in IMAP (fast search/counts on large mailboxes) and SMTP (clean sending, no macOS 15+ <blockquote> wrapping) backends are configured via non-secret APPLE_MAIL_MCP_* settings — supplied in an env block or, for hosts that strip env (e.g. Claude Desktop), a config.json at ~/Library/Application Support/apple-mail-mcp/config.json (loaded into the environment at startup) — with passwords kept in the macOS Keychain. Don't reverse-engineer it: the full walkthrough is docs/IMAP-SETUP.md (app passwords, Keychain, both config methods, multi-account, SMTP, headless/SSH Keychain gotchas). Verify with the doctor tool.

Critical: Backslash Escaping

When sending content with backslashes to any tool, you MUST escape them.

The MCP protocol uses JSON for parameters. In JSON, \ is an escape character. To include a literal backslash:

You want	Send in JSON parameter
`\`	`\\`
`\\`	`\\\\`
`Mobile\ Documents`	`Mobile\\ Documents`

Why This Matters

If you send a single backslash without escaping:

The JSON parser interprets \ as an escape sequence
Invalid sequences like \ (backslash-space) cause silent failures
The email send/draft may fail with no clear error

Examples

Correct - shell path with an escaped space:

body: "Run: cp ~/Library/Mobile\\ Documents/report.pdf ~/Desktop/"

→ arrives as: Run: cp ~/Library/Mobile\ Documents/report.pdf ~/Desktop/

Read the full file on GitHub · 455 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

10d ago Changed · +1 lines · +243 tokens per session 95ee2165fc6e
18d ago Changed · +3 lines · +75 tokens per session c97c29e2cc0f
20d ago Changed · +5 lines · +167 tokens per session f9321baf8529
22d ago Changed · +5 lines · +316 tokens per session 2458a7fc789f
1mo ago Changed · +2 lines · +52 tokens per session 14152f6a6b9f
1mo ago Changed · +1 lines · +170 tokens per session 2aa6e9baabaa
1mo ago Changed · +106 tokens per session 84869285e63b
1mo ago Changed · +1 lines · +149 tokens per session 1420edd17c81
1mo ago Changed · +6 lines · +147 tokens per session da639c1a9ddf
1mo ago First seen · 431 lines · 5,071 tokens per session scan A d11d6ac5dae6

Subscribe to this mod's changes

apple-mail-mcp CLAUDE.md is an instructions file published in the GitHub repository sweetrb/apple-mail-mcp (102 stars, last pushed today), licensed MIT. It adds 6,496 tokens to every session, about $0.0260 per session on Opus 5.5. A static security scan graded it A with 1 finding (runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

apple apple-mail applescript claude email macos

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 9,715 tokens

apple-mail-mcp: Instructions file for Claude Code