{"id":50525554,"url":"https://github.com/maximbilan/apple-mail-mcp-go","last_synced_at":"2026-06-03T07:31:25.227Z","repository":{"id":356937145,"uuid":"1234449749","full_name":"maximbilan/apple-mail-mcp-go","owner":"maximbilan","description":"Go MCP server for Apple Mail on macOS: read, search, send, and organize Mail.app messages.","archived":false,"fork":false,"pushed_at":"2026-05-10T15:15:50.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T15:36:39.400Z","etag":null,"topics":["apple-mail","applescript","claude-code","claude-desktop","golang","macos","mail-app","mcp","model-context-protocol"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximbilan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T07:45:20.000Z","updated_at":"2026-05-10T15:16:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximbilan/apple-mail-mcp-go","commit_stats":null,"previous_names":["maximbilan/apple-mail-mcp-go"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maximbilan/apple-mail-mcp-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fapple-mail-mcp-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fapple-mail-mcp-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fapple-mail-mcp-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fapple-mail-mcp-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximbilan","download_url":"https://codeload.github.com/maximbilan/apple-mail-mcp-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fapple-mail-mcp-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33853984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-mail","applescript","claude-code","claude-desktop","golang","macos","mail-app","mcp","model-context-protocol"],"created_at":"2026-06-03T07:31:24.257Z","updated_at":"2026-06-03T07:31:25.216Z","avatar_url":"https://github.com/maximbilan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# apple-mail-mcp\n\n[![CI](https://github.com/maximbilan/apple-mail-mcp-go/actions/workflows/ci.yml/badge.svg)](https://github.com/maximbilan/apple-mail-mcp-go/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/maximbilan/apple-mail-mcp-go)](https://github.com/maximbilan/apple-mail-mcp-go/releases)\n[![License](https://img.shields.io/github/license/maximbilan/apple-mail-mcp-go?cacheSeconds=300)](https://github.com/maximbilan/apple-mail-mcp-go/blob/main/LICENSE)\n\n`apple-mail-mcp` is a Go Model Context Protocol (MCP) server for macOS that gives MCP-compatible assistants programmatic access to Mail.app for listing accounts/mailboxes, searching and reading messages, sending drafts/emails, and unread-count workflows.\n\n## Prerequisites\n\n- macOS 12+\n- Mail.app configured with at least one account\n- Go 1.22+ (only required for building from source)\n\n## Installation\n\n### 1. One-click for Claude Desktop\n\nDownload `apple-mail-mcp.mcpb` from the [latest release](https://github.com/maximbilan/apple-mail-mcp-go/releases/latest) and double-click it. Claude Desktop installs and registers the server automatically.\n\n### 2. One-line install (recommended for Claude Code or both clients)\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/maximbilan/apple-mail-mcp-go/main/install.sh | sh\n```\n\nThis installer:\n- Detects macOS architecture and installs `~/.local/bin/apple-mail-mcp`\n- Uses local `go build`/`go install` when Go exists, otherwise downloads the latest release binary and verifies SHA256\n- Detects Claude Desktop and/or Claude Code and offers registration\n\n### 3. Build from source (Go developers)\n\n```sh\ngo install github.com/maximbilan/apple-mail-mcp-go/cmd/apple-mail-mcp@latest\napple-mail-mcp install\n```\n\n### 4. Manual configuration\n\nClaude Desktop config path:\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\nAdd/update:\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-mail\": {\n      \"command\": \"/Users/\u003cyou\u003e/.local/bin/apple-mail-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nClaude Code:\n\n```sh\nclaude mcp add apple-mail \"$HOME/.local/bin/apple-mail-mcp\" --scope user\n```\n\n## Permissions\n\nThe first time `osascript` controls Mail.app, macOS shows an Automation permission prompt.\nGrant access for the calling process (for example Terminal, Claude Desktop, or Claude Code).\nIf needed, manage this at:\n\n`System Settings -\u003e Privacy \u0026 Security -\u003e Automation`\n\n## Tool Reference\n\nGenerated from registered tools via:\n\n```sh\ngo run ./cmd/apple-mail-mcp tools-docs\n```\n\n| Name | Params | Description |\n|---|---|---|\n| list_accounts | none | List account names configured in Mail.app. |\n| list_mailboxes | account (string, required) | List mailboxes for an account with unread counts. |\n| search_messages | account (required), mailbox, sender_contains, subject_contains, unread_only, date_from, date_to, limit | Search messages with server-side filters. |\n| get_message | message_id (required), include_body | Get message metadata and optionally full body. |\n| get_unread_count | account (optional) | Get total and per-mailbox unread counts. |\n| send_email | to, subject, body, cc, bcc, account | Send a plaintext email immediately. |\n| create_draft | to, subject, body, cc, bcc, account | Create a draft email without sending. |\n| mark_as_read | message_ids, read | Mark messages as read/unread (max 100 ids). |\n\n## Running\n\nStart over stdio transport:\n\n```sh\napple-mail-mcp --log-level info\n```\n\nRead-only mode (write tools hidden):\n\n```sh\napple-mail-mcp --read-only\n```\n\n## Known Limitations\n\n- Some Mail messages can have missing/malformed date metadata. `search_messages` falls back from `date sent` to `date received`, and date can be empty when unavailable.\n- Gmail label model can surface `All Mail` semantics. `search_messages` mailbox output reflects the mailbox requested in the query (for example `INBOX`) to avoid confusion.\n\n## Integration Tests\n\nIntegration tests require Mail.app on macOS and explicit build tag:\n\n```sh\ngo test ./tests/integration -tags=integration -v\n```\n\n## Troubleshooting\n\n- Mail.app not responding:\n  - Open Mail.app once and ensure account sync completes.\n- Permission denied:\n  - Re-check macOS Automation permissions for the process invoking the server.\n- AppleScript timeout:\n  - Open Mail.app, wait for sync to settle, then retry.\n  - Increase timeout with `APPLE_MAIL_MCP_TIMEOUT` (e.g. `120s` or `180`).\n- Config did not update:\n  - Restart Claude Desktop and run `claude mcp list` for Claude Code.\n\n## Release Validation Checklist\n\nBefore creating a public release:\n\n```sh\ngo build ./...\ngo vet ./...\ngo test ./... -race\n```\n\nInstall path smoke checks:\n\n```sh\n./install.sh\napple-mail-mcp install --yes\napple-mail-mcp uninstall --yes\n```\n\n## Uninstall\n\n```sh\n./uninstall.sh\n```\n\nOr if installed from `go install`:\n\n```sh\napple-mail-mcp uninstall\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fapple-mail-mcp-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximbilan%2Fapple-mail-mcp-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fapple-mail-mcp-go/lists"}