convez.ai
MCP ServerAutomaçãoIntermediário
Agentic-Assets

Apple Mail MCP Server

Agentic-Assets/apple-mail-mcp

Acesso programático completo ao Apple Mail para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta assistentes IA ao Apple Mail, oferecendo leitura, busca, composição, organização e análise de emails via linguagem natural. Inclui 28 ferramentas testadas, integração com FastMCP e suporte completo a automação de fluxos de trabalho com 9 skills pré-configurados.

Instalação

$npx convez-ai Agentic-Assets/apple-mail-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 1 dia
Versão
v3.12.3
Issues abertas
3
Contribuidores
12

Casos de uso

  • Automação de triagem e organização de emails em massa
  • Análise e resumo de conversas de email via linguagem natural
  • Integração de buscas de email em fluxos de trabalho de IA
  • Composição assistida e resposta automática a emails com contexto

Veredito

Servidor maduro e bem-testado que expõe a API do Apple Mail para agentes Claude com 28 ferramentas especializadas. Recomendado para usuários macOS que buscam automação profunda de email integrada a workflows de IA, com suporte direto em Claude Code.

README

A tradução para o português deste README ainda está na fila.

Apple Mail MCP Server

License: MIT PyPI Python 3.10+ MCP GitHub stars

Star History

An MCP server that gives AI assistants full access to Apple Mail -- read, search, compose, organize, and analyze emails via natural language. Built with FastMCP (fastmcp>=3.1.0,<4). 28 tools, 822 tests, Python 3.10+.

Documentation map

DocPurpose
CLAUDE.mdRoot navigation hub for agents
docs/CLAUDE-conventions.mdTool performance rules, read-only, skills, plugin-dev
docs/AGENT_LIVE_TESTING.mdLive Mail verification via apple-mail CLI
plugin/docs/CLAUDE.mdPlugin wrapper & start_mcp.sh
plugin/apple_mail_mcp/CLAUDE.mdPackage entry, core.py, CLI
plugin/apple_mail_mcp/tools/CLAUDE.mdMCP tool modules
plugin/skills/CLAUDE.mdSkill authoring
tests/CLAUDE.mdTest layout & AppleScript mocks
tools/CLAUDE.mdManifest validation scripts
docs/CLAUDE.mdDocs folder index + plugin skill map
tasks/CLAUDE.mdPhase plans & backlog
apple-mail-mcpb/CLAUDE.mdDesktop bundle build
.claude-plugin/CLAUDE.mdClaude Code marketplace manifest
.agents/plugins/marketplace.jsonCodex Desktop/CLI marketplace manifest

Quick Install

Prerequisites: macOS with Apple Mail configured, Python 3.10+

Claude Code Plugin (Recommended)

One install — MCP server (28 tools) and nine bundled workflow skills under plugin/skills/ (see table below). Workflow entry points are skills-only; the old /email-management slash command was retired to avoid duplicate skill/command exposure.

claude plugin marketplace add Agentic-Assets/apple-mail-mcp
claude plugin install apple-mail@apple-mail-mcp

Then restart Claude Code.

Codex Desktop / CLI Plugin

Codex uses the repo marketplace at .agents/plugins/marketplace.json, which points at the shared plugin/ runtime and plugin/.codex-plugin/plugin.json.

codex plugin marketplace add Agentic-Assets/apple-mail-mcp
codex plugin add apple-mail@apple-mail-mcp

For a local checkout:

cd /path/to/apple-mail-mcp
codex plugin marketplace add .
codex plugin add apple-mail@apple-mail-mcp

MCP-only fallback, still draft-safe:

codex mcp add apple-mail -- /bin/bash /path/to/apple-mail-mcp/plugin/start_mcp.sh --draft-safe

If mcp__apple-mail__* tools are absent after plugin install, treat that as an MCP registration failure. Do not create reply drafts with generic AppleScript, Mail UI scripting, shell osascript, or standalone compose fallbacks. Fix registration first, or use the MCP-only absolute-path fallback above, restart Codex, and confirm the Apple Mail tools are present before drafting.

How to know it worked: codex plugin list showing installed, enabled is not enough. The pass condition is that the active Codex session exposes mcp__apple-mail__* tools and an MCP list_tools handshake includes reply_to_email. Maintainers can run bash tools/validate-codex-plugin.sh to check that install plus runtime path in a temporary CODEX_HOME.

Restart Codex Desktop or start a fresh Codex CLI session after installing.

Refresh another Mac / second computer

Use this when another computer has an older Apple Mail plugin install, stale marketplace cache, or you want to prove both Codex and Claude Code are using the same current checkout.

  1. Get the current code:
cd ~/Documents/GitHub/agentic-assets/apple-mail-mcp
git switch main && git pull --ff-only
  1. Refresh Codex from the local checkout:
codex plugin remove apple-mail@apple-mail-mcp || true
codex plugin marketplace remove apple-mail-mcp || true
codex plugin marketplace add ./
codex plugin add apple-mail@apple-mail-mcp
codex mcp get apple-mail --json

The Codex MCP registration should show:

{
  "command": "/bin/bash",
  "args": ["./start_mcp.sh", "--draft-safe"]
}

codex plugin list showing installed, enabled is not enough. For a runtime smoke, run:

python3 -m venv .venv
.venv/bin/pip install -e . pytest
.venv/bin/python tools/mcp_tool_smoke.py \
  --command /bin/bash \
  --arg ./start_mcp.sh \
  --arg=--draft-safe \
  --cwd "$PWD/plugin" \
  --expect-count 28 \
  --required-tool reply_to_email \
  --required-tool compose_email \
  --required-tool manage_drafts \
  --required-tool list_accounts \
  --required-tool get_inbox_overview
  1. Refresh Claude Code from the local checkout:
claude plugin uninstall apple-mail@apple-mail-mcp --scope user --keep-data -y || true
claude plugin marketplace remove apple-mail-mcp || true
claude plugin marketplace add ./ --scope user
claude plugin install apple-mail@apple-mail-mcp --scope user
claude plugin details apple-mail@apple-mail-mcp

Prefer --scope user for personal machine setup. Project-scope marketplace entries can write an absolute local path into .claude/settings.json, which is usually not what you want to commit.

claude plugin details apple-mail@apple-mail-mcp should report version 3.7.1 and MCP servers (1) apple-mail. To smoke the installed Claude cache directly, replace the path below if the details output shows a different install path:

.venv/bin/python tools/mcp_tool_smoke.py \
  --command /bin/bash \
  --arg "$HOME/.claude/plugins/cache/apple-mail-mcp/apple-mail/3.7.1/start_mcp.sh" \
  --arg=--draft-safe \
  --cwd "$HOME/.claude/plugins/cache/apple-mail-mcp/apple-mail/3.7.1" \
  --expect-count 28 \
  --required-tool reply_to_email \
  --required-tool compose_email \
  --required-tool manage_drafts \
  --required-tool list_accounts \
  --required-tool get_inbox_overview
  1. Restart clients:

After either refresh, restart Codex Desktop / start a fresh Codex CLI session and restart Claude Code so they load the refreshed plugin process.

Claude Desktop Cowork (plugin marketplace)

Cowork uses Anthropic's remote marketplace backend (remoteMarketplaceClient), which currently rejects most third-party GitHub marketplaces with a generic "Failed to add marketplace" even when the repo is valid. This is a known Cowork/Desktop bug, not a problem with this fork's manifest. Claude Code CLI install (above) works; Cowork's GitHub sync often does not.

Workaround — upload the .plugin file directly (recommended for Cowork):

  1. Build the artifacts: bash tools/build-artifacts.sh — produces apple-mail.plugin, apple-mail-plugin.zip, and apple-mail-mcp-v{VERSION}.mcpb at the repo root.
  2. Cowork → Customize → Add plugin → Upload plugin.
  3. Select apple-mail.plugin and enable Apple Mail.

apple-mail.plugin and apple-mail-plugin.zip are byte-identical — both work, the .plugin extension is the canonical Cowork upload format.

cd /path/to/apple-mail-mcp
bash tools/build-artifacts.sh   # produces apple-mail.plugin, apple-mail-plugin.zip, and .mcpb

If you must build the zip by hand, zip from inside plugin/ so .claude-plugin/plugin.json sits at the zip root — Cowork rejects uploads where it is nested under plugin/:

cd /path/to/apple-mail-mcp/plugin
zip -rq -X -D ../apple-mail-plugin.zip . \
  -x 'venv/*' '*/__pycache__/*' '*.pyc' '*.DS_Store' 'CLAUDE.md' '*/CLAUDE.md'

Important: Apple Mail MCP requires macOS Mail.app on the host Mac (start_mcp.sh → AppleScript). Cowork's Linux VM cannot run Mail directly; the plugin MCP server must execute on your Mac host. If tools fail after upload, use the Claude Code CLI install or the Desktop .mcpb path below instead.

GitHub marketplace URL (when Cowork sync works): Agentic-Assets/apple-mail-mcp

Other Install Methods

This fork includes a maintained apple-mail CLI that wraps the same Python tool code as the MCP server. It is meant for humans, shell scripts, smoke tests, and agents on another Mac.

git clone https://github.com/Agentic-Assets/apple-mail-mcp.git
cd apple-mail-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

.venv/bin/apple-mail accounts --json
.venv/bin/apple-mail search --account "Gmail" --query "invoice" --limit 10 --json
.venv/bin/apple-mail show --account "Gmail" --id 12345 --json
.venv/bin/apple-mail draft --account "Gmail" --to person@example.com --subject "Draft" --body "Draft body" --signature-name "TU"
.venv/bin/apple-mail quick-check --account "Gmail" --json
.venv/bin/apple-mail perf-test --account "Gmail" --json
.venv/bin/apple-mail perf-test --include-analysis --allow-heavy-mail-scan --account "Gmail" --json
.venv/bin/apple-mail smoke-test --account "Gmail" --json

See docs/AGENT_LIVE_TESTING.md for batteries, permissions, and when to use each command.

Generate draft-safe Claude/OpenClaw MCP config from the same checkout:

.venv/bin/apple-mail mcp-config --repo "$(pwd)"
claude mcp add apple-mail -- uvx mcp-apple-mail

Or for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "uvx",
      "args": ["mcp-apple-mail"]
    }
  }
}
pip install mcp-apple-mail
claude mcp add apple-mail -- mcp-apple-mail

For Claude Desktop chat (outside of Cowork mode):

  1. Download apple-mail-mcp-v{VERSION}.mcpb from Releases or build locally with bash tools/build-artifacts.sh.
  2. In Claude Desktop, open Settings → Extensions (or Developer → MCP Servers → Install from file depending on app version), pick Add Custom Plugin / Install from file, and select the .mcpb.
  3. Grant the Automation + Mail Data Access prompts macOS surfaces on first run.
  4. Restart Claude Desktop so the extension registers across chat and Cowork sessions. Cowork projects may need to enable the extension explicitly in the project's plugin settings.

The bundle bootstraps a per-install Python venv via start_mcp.sh on first run, so python3 must be on PATH for the Claude Desktop process. For pure Cowork use, prefer the .plugin upload above (same MCP server, no Developer mode required).

git clone https://github.com/Agentic-Assets/apple-mail-mcp.git
cd apple-mail-mcp/plugin
python3 -m venv venv
venv/bin/pip install -r requirements.txt

claude mcp add apple-mail -- /bin/bash $(pwd)/start_mcp.sh

Tools (28)

Reading & Search

ToolDescription
get_inbox_overviewDashboard with unread counts, folders, and recent emails
list_inbox_emailsList emails (defaults to 50 most recent). Async parallel per-account dispatch
get_mailbox_unread_countsUnread counts per mailbox or per-account summary
list_accountsList all configured Mail accounts
list_account_addressesList sender aliases configured for a Mail account
search_emailsUnified search — subject, sender, body, dates, attachments. Defaults to last 48h and the default account
get_email_by_idFetch one exact email by the Apple Mail message id returned from search results
get_email_threadConversation thread view across Inbox + Sent; prefer message_id from search/list results

Organization

ToolDescription
list_mailboxesFolder hierarchy with optional message counts
create_mailboxCreate new mailboxes (supports nested paths)
move_emailMove by message_ids (preferred) or filters with allow_filter_scan=True. Default max 50
update_email_statusMark read/unread, flag/unflag by message_ids (preferred) or filters with allow_filter_scan=True. Default max 10
manage_trashSoft delete, permanent delete, empty trash; prefer message_ids, filters need allow_filter_scan=True. Default max 5
synchronize_accountExplicitly confirmed Mail.app sync for an account (can fetch large backlogs)

Composition

ToolDescription
compose_emailCreate a new standalone draft by default; refuses reply-like subjects/bodies unless standalone_confirmed=True; does not include original thread context
reply_to_emailNative Mail reply or reply-all draft with Mail-generated quoted thread context; prefer message_id from search/list results
forward_emailForward with optional message, CC/BCC; prefer message_id from search/list results
manage_draftsCreate, list, send, and delete drafts; standalone create refuses reply-like drafts unless standalone_confirmed=True (send blocked in --read-only and --draft-safe)
create_rich_email_draftBuild a standalone multipart HTML .eml draft and save it to Drafts by default; refuses reply-like drafts unless standalone_confirmed=True

Attachments

ToolDescription
list_email_attachmentsList attachments by message_ids (preferred) or subject keyword (capped at 50 by default)
save_email_attachmentSave attachments to disk (validates target path)

Smart Inbox

ToolDescription
get_awaiting_replySent emails that haven't received a reply (default last 7 days)
get_needs_responseUnread emails likely needing a response (filters out newsletters/automated)
get_top_sendersMost frequent senders by count or domain over a date window

Analytics & Export

ToolDescription
get_statisticsAccount overview, sender stats, or mailbox breakdown; short windows scan 10 mailboxes × 75 messages, longer windows 20 × 250
export_emailsExport single emails by message_id or subject, or full mailboxes to TXT/HTML (default cap 1000)
inbox_dashboardInteractive UI dashboard (requires mcp-ui-server)
full_inbox_exportAudited full-inbox walk; only tool that scans every message. Slow (minutes on 24K mailboxes). Named in UNBOUNDED_SCAN_REQUIRED remediation as the legitimate fallback.

Configuration

Read-Only Mode

Pass --read-only to disable tools that send email (compose_email, reply_to_email, forward_email). Draft management remains available (list, create, delete) but sending a draft via manage_drafts is blocked.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/apple_mail_mcp.py", "--read-only"]
    }
  }
}

Draft-Safe Mode

Pass --draft-safe to keep read, search, draft, and open-for-review workflows available while blocking actual sends. This is the recommended mode for shared agent workspaces.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/plugin/start_mcp.sh",
      "args": ["--draft-safe"]
    }
  }
}

In draft-safe mode:

  • compose_email, reply_to_email, and forward_email default to mode="draft" (quiet save to Drafts, no leftover compose windows); native replies verify the saved draft in a bounded newest-Drafts check before reporting success
  • they apply DEFAULT_MAIL_SIGNATURE by default when set; pass include_signature=False or CLI --no-signature to suppress it
  • use mode="open" only when you want each draft saved and left open in Mail for review (bulk reply UIs)
  • reply drafting requires reply_to_email(message_id=...); standalone draft creators (compose_email, create_rich_email_draft, manage_drafts(action="create")) block reply-like Re: / Fwd: drafts unless standalone_confirmed=True
  • treat subject_keyword reply targeting or any degraded reply fallback as Cayman-approved-only for the specific message
  • pass message_id from search/list tools for reply/forward when available; subject_keyword is fallback only
  • explicit mode="send" calls return an error
  • manage_drafts action="send" returns an error

Default Mail Account

Set DEFAULT_MAIL_ACCOUNT to make most tools default to one account instead of scanning every configured Mail account. This is the single biggest perf win on multi-account setups. Tools still accept an explicit account parameter to override, and you can pass all_accounts=True to a tool that supports it for explicit cross-account scope.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/apple_mail_mcp.py"],
      "env": {
        "DEFAULT_MAIL_ACCOUNT": "Work"
      }
    }
  }
}

Use the exact account name as it appears in Apple Mail (e.g. Gmail, Work, iCloud). Leave unset to query all accounts by default.

User Preferences (Optional)

Set USER_EMAIL_PREFERENCES to give the assistant context about your workflow. The string is injected into every preference-aware tool's docstring so the model sees it as part of the tool description.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/apple_mail_mcp.py"],
      "env": {
        "DEFAULT_MAIL_ACCOUNT": "Work",
        "USER_EMAIL_PREFERENCES": "Prefer Archive folder over Trash, show max 25 emails, default to last week for triage"
      }
    }
  }
}

For .mcpb installs, configure both under Claude Desktop → Developer > MCP Servers > Apple Mail MCP (the bundle exposes them via user_config).

Default Mail Signature

Set DEFAULT_MAIL_SIGNATURE to the exact Apple Mail signature name you want applied to new compose, reply, and forward drafts. Per-call signature_name overrides the default; include_signature=False disables it for one call. The CLI exposes this as apple-mail draft --signature-name "TU" and --no-signature.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/plugin/start_mcp.sh",
      "args": ["--draft-safe"],
      "env": {
        "DEFAULT_MAIL_ACCOUNT": "Work",
        "DEFAULT_MAIL_SIGNATURE": "TU"
      }
    }
  }
}

Performance Defaults

To stay fast on large mailboxes (24K+ messages), the server applies conservative defaults you can opt out of per-call:

DefaultToolsOverride
Last 48 hourssearch_emails, get_awaiting_reply, get_needs_response, get_top_sendersPass recent_days=N (e.g. 7 for a week); routine tools reject unbounded scans
50 emails maxlist_inbox_emails, list_email_attachmentsPass max_emails / max_results
Single accountAll scoped tools when DEFAULT_MAIL_ACCOUNT is setPass account=<name> or all_accounts=True
Per-call timeoutAll long-running toolsPass timeout=<seconds>
Unbounded scans refusedAll routine scan/search tools (recent_days=0 / max_emails=0)Returns structured error code: UNBOUNDED_SCAN_REQUIRED; full_inbox_export is a separate audited export tool, not a normal search fallback
ID-first mutationsmove_email, update_email_status, manage_trashPass message_ids=[...] from search_emails or list_inbox_emails (fast, preferred). Filter-based bulk moves/updates/trash require allow_filter_scan=True or return code: FILTER_SCAN_DISABLED.
Gated filter scansmove_email, update_email_status, manage_trash (filter path only)allow_filter_scan=True (slow; timeout-prone on 24k+ inboxes). Filter paths still default to a 48h recent_days window.
Body scan gatesearch_emailsbody_text requires allow_body_scan=True or returns code: BODY_SCAN_DISABLED. Prefer subject/sender/date filters; pair body scans with a tight date window.

Recommended mutation flow: search or list → collect message_id values → call move_email, update_email_status, or manage_trash with message_ids. Use dry_run=True with ids for a fast preview without acting.

When a per-account call fails in a multi-account fan-out, you get partial results plus an errors field naming the account. JSON responses also include error_details when the tool can distinguish a timeout from another Mail/App permission error.

Safety Limits (destructive ops)

Batch operations cap by default to prevent accidental bulk actions. Override via the per-tool parameter when needed.

OperationDefault capParam
move_email50max_moves
update_email_status10max_updates
manage_trash5max_deletes
export_emails1000max_emails

Dry-run defaults: manage_trash defaults to dry_run=True (safe preview — explicit override needed to act, especially for action="delete_permanent"). move_email and update_email_status default to dry_run=False (live) because their effects are reversible; pass dry_run=True to preview matches first.

Usage Examples

Show me an overview of my inbox
Search for emails about "project update" in my Gmail
Reply to the email about "Domain name" with "Thanks for the update!"
Move emails with "invoice" in the subject to my Archive folder
Show me email statistics for the last 30 days
Draft replies to unread messages with mode=open for review, or create a rich HTML weekly-update draft

CLI

Install from a repo checkout:

python3 -m venv .venv
.venv/bin/pip install -e .

Common commands:

apple-mail accounts --json
apple-mail addresses --json
apple-mail inbox --account "Gmail" --limit 10 --json
apple-mail search --account "Gmail" --query "invoice" --limit 10 --json
apple-mail show --account "Gmail" --id 12345 --json
apple-mail mailboxes --account "Gmail" --json
apple-mail mailboxes --account "Gmail" --counts --json   # slower; explicit counts opt-in
apple-mail draft --account "Gmail" --to person@example.com --subject "Draft" --body "Draft body" --signature-name "TU"
apple-mail mcp-config --repo "$(pwd)"
apple-mail quick-check --account "Gmail" --json
apple-mail perf-test --account "Gmail" --json
apple-mail perf-test --include-analysis --allow-heavy-mail-scan --account "Gmail" --json
apple-mail smoke-test --account "Gmail" --json

Live verification guide: docs/AGENT_LIVE_TESTING.md.

Use perf-test --include-analysis --allow-heavy-mail-scan only when you explicitly want the heavy analysis gate (needs-response, awaiting-reply, top-senders, statistics). Routine validation should use quick-check, smoke-test, or perf-test without analysis.

The CLI keeps write operations draft-first. It intentionally does not expose send/delete shortcuts; use the MCP tools with --draft-safe for shared agents.

Rich HTML Drafts

Use create_rich_email_draft when you need a visually formatted email, newsletter, or leadership update.

  • It generates an unsent .eml file with multipart plain-text + HTML bodies
  • It saves the opened Mail compose window to Drafts by default, then closes the fresh window
  • It can leave the saved draft open for explicit human review (review_in_mail=True)
  • It can write only the .eml artifact with open_in_mail=False
  • Blank subjects stay .eml-only until there is a subject to save safely through Mail
  • It accepts partial details, so you can start with just an account and subject and fill in the rest later

This is more reliable than injecting raw HTML into AppleScript content, which Mail often stores as literal markup.

Claude Code Skills

Workflow skills ship with the Claude Code and Codex plugin installs and load automatically on install (see plugin/skills/CLAUDE.md for routing):

SkillPurpose
apple-mail-operatorMCP + Mail setup, accounts/mailboxes, safe navigation, performance
inbox-triage5–10 min read-first scan (needs-response, awaiting-reply)
email-managementSustained Inbox Zero habits and cross-cutting programs
mailbox-taxonomyFolder strategy, noise diagnosis, structural create_mailbox
email-archive-cleanupStaged archive / bulk move / trash with dry runs + exports
mail-rules-advisorMail filter / rule proposals (manual apply in Mail.app)
email-draftingCompose, reply, forward, rich drafts (--draft-safe aware)
email-style-profileLearn voice from Sent mail + preferences for drafting
email-attachmentsList and save attachments with path safety

For standalone MCP installs, copy the needed skill directories manually (example loop):

for d in apple-mail-operator inbox-triage email-management mailbox-taxonomy \
         email-archive-cleanup mail-rules-advisor email-drafting \
         email-style-profile email-attachments; do
  cp -r "plugin/skills/$d" "$HOME/.claude/skills/$d"
done

The plugin MCP server starts with --draft-safe by default for both Claude Code (plugin/.claude-plugin/plugin.json) and Codex (plugin/.mcp.json).

Requirements

  • macOS with Apple Mail configured
  • Python 3.10+
  • fastmcp>=3.1.0,<4 and mcp-ui-server==1.0.0 for the MCP Apps dashboard
  • Claude Desktop, Codex Desktop/CLI, or any MCP-compatible client
  • Mail.app permissions: Automation + Mail Data Access (grant in System Settings > Privacy & Security > Automation)

Troubleshooting

IssueFix
Mail.app not respondingEnsure Mail.app is running; check Automation permissions in System Settings
Slow searches on a large accountSet DEFAULT_MAIL_ACCOUNT to the account you actually work in. Pair account= with recent_days= (default 48h) for tight scopes. Pass include_content=False if you don't need bodies
One account fails across a fan-outReturned JSON includes an errors array naming the account plus error_details when available. The other accounts' results are still returned. Bump timeout= for timeout entries; fix Mail permissions or account config for non-timeout entries
Mailbox not foundUse exact folder names; nested folders use / separator (e.g., Projects/Alpha)
Permission errorsGrant access in System Settings > Privacy & Security > Automation
Rich draft shows raw HTMLUse create_rich_email_draft instead of pasting HTML into manage_drafts or AppleScript content
Save / Don't Save when closing draftsUse default mode="draft" or mode="open" (saves first). Avoid leaving unsaved compose windows from bulk agent runs

Project Structure

apple-mail-mcp/
├── .agents/
│   └── plugins/
│       └── marketplace.json   # Codex Desktop/CLI marketplace entry
├── .claude-plugin/
│   └── marketplace.json       # Claude Code marketplace manifest
├── plugin/                    # Shared Claude Code + Codex plugin runtime
│   ├── .codex-plugin/
│   │   └── plugin.json        # Codex plugin manifest
│   ├── .claude-plugin/
│   │   └── plugin.json        # Claude Code plugin manifest
│   ├── .mcp.json              # Codex MCP config
│   ├── skills/                # bundled workflow skills (see plugin/skills/CLAUDE.md)
│   ├── apple_mail_mcp/        # Python MCP server package (28 tools)
│   ├── apple_mail_mcp.py      # Entry point
│   ├── start_mcp.sh           # Startup wrapper (auto-creates venv)
│   └── requirements.txt
├── apple-mail-mcpb/           # MCPB build files (Claude Desktop)
├── LICENSE
└── README.md

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit and push
  4. Open a Pull Request

License

MIT -- see LICENSE.

Links

Ver o original no GitHub

Bom para

Relacionados