Apple Mail MCP

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/imdinu-apple-mail-mcp

About

Use cases: email

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools

8 read · 0 write · 0 deleteRead-only

Secrets

None asked for

Install scripts

None found

Runs as

Python package

Tools (8)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

• get_attachment

  DEPRECATED: Use get_email_attachment() or get_email_links(). Extract resources from an email: attachments or links. Delegates to get_email_links (filename omitted) or get_email_attachment (filename provided). Args: message_id: The email's unique ID filename: Attachment filename to extract. If omitted, returns links instead. account: Account name (optional) mailbox: Mailbox name (optional)

• get_email

  Get a single email with full content. Looks up the email across all accounts using a cascade strategy. Just pass the message_id — account/mailbox are optional hints that speed up lookup but are not required. Args: message_id: The email's unique ID (from search results) account: Optional hint (speeds up lookup, not required) mailbox: Optional hint (speeds up lookup, not required) Returns: Email dictionary with full content including: - id, subject, sender, date_received, date_sent - content: Full plain text body - read, flagged status - reply_to, message_id (e…

• get_email_attachment

  Extract a file attachment from an email and save to disk. Saves the attachment under ~/.apple-mail-mcp/attachments/. Parses the raw MIME structure, so it works for all attachment types including inline images and S/MIME signatures. Requires the search index. Args: message_id: The email's unique ID filename: Attachment filename to extract account: Account name (optional, speeds up lookup) mailbox: Mailbox name (optional, speeds up lookup) Returns: Dict with filename, mime_type, size, and file_path pointing to the saved file. Example: >>> get_email_attachment(123…

• get_email_links

  Extract hyperlinks from an email's HTML content. Filters out mailto:, javascript:, and long tracking URLs. Returns deduplicated links with their anchor text. Requires the search index. Args: message_id: The email's unique ID account: Account name (optional, speeds up lookup) mailbox: Mailbox name (optional, speeds up lookup) Returns: Dict with 'links' list, each having 'url' and 'text'. Example: >>> get_email_links(12345) {"links": [{"url": "https://...", "text": "Click"}]}

• get_emails

  Get emails from a specific mailbox with optional filtering. Note: This tool lists emails from a single mailbox. To search across all mailboxes, use the search() tool instead. Args: account: Account name. Uses APPLE_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses APPLE_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified. filter: Filter type: - "all": All emails (default) - "unread": Only unread emails - "flagged": Only flagged emails - "today": Emails received today -…

• list_accounts

  List all configured email accounts in Apple Mail. Returns: List of account dictionaries with 'name' and 'id' fields. Example: >>> list_accounts() [{"name": "Work", "id": "abc123"}, {"name": "Personal", "id": "def456"}]

• list_mailboxes

  List all mailboxes for an email account. Args: account: Account name. Uses APPLE_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. Returns: List of mailbox dictionaries with 'name' and 'unreadCount' fields. Example: >>> list_mailboxes("Work") [{"name": "INBOX", "unreadCount": 5}, ...]

• search

  Search emails across all accounts and mailboxes. Uses full-text search index for fast results (~2ms). All scopes search across every account and mailbox unless filtered. Query tips: - Use 2-3 specific keywords, not full sentences - Terms are AND-ed: "budget Q1" finds emails with BOTH words - Use quotes for exact phrases: '"quarterly report"' - Prefix search: "meet*" matches meeting, meetings, etc. - The default scope "all" searches subject + sender + body together Args: query: Search keywords (2-3 specific terms work best). Do NOT use long natural-language phrases. account: …

Signals

Stars

74

Forks

29

Open issues

17

Contributors

5

Weekly downloads

249

Last commit

Oct 8, 2026 (22 days ago)

Last release

Sep 14, 2026 (1 month ago)

Last package publish

Sep 14, 2026 (1 month ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name

io.github.imdinu/apple-mail-mcp

Version

0.5.0

Auth

No auth

Packages

pypi apple-mail-mcp

License

GPL-3.0

Repository

github.com/imdinu/apple-mail-mcp

First seen

Oct 24, 2026

Last checked

Oct 24, 2026

Source

Official MCP Registrygithub-graphql