{
  "markdown": "# Apple App MCP\n\nWorkspace for MCP servers that expose local Apple app data to assistants.\n\n## Packages\n\n| Package | Status | Purpose |\n|---------|--------|---------|\n| [`mac-mail-mcp`](packages/mac-mail-mcp/) | Beta | Mac Mail MCP server with disk-first reads and full-coverage FTS5 body search. |\n| [`mac-calendar-mcp`](packages/mac-calendar-mcp/) | Alpha | Read-only Mac Calendar MCP server with indexed archive search. |\n\n## Quick Start\n\nInstall the package you want:\n\n```bash\npipx install mac-mail-mcp\npipx install mac-calendar-mcp\n```\n\nBuild local indexes for fast search:\n\n```bash\nmac-mail-mcp index --verbose\nmac-calendar-mcp authorize\nmac-calendar-mcp index\n```\n\nCalendar authorization installs a small helper app with a stable macOS privacy\nidentity. Approve its Full Calendar Access prompt once so terminal, MCP, and\nscheduled launchd rebuilds can use EventKit consistently. EventKit runs inside\nthat signed app identity; the Calendar MCP does not execute the helper's script\nthrough an anonymous `osascript` process.\n\nGenerate optional config files:\n\n```bash\nmac-mail-mcp init\nmac-calendar-mcp init\n```\n\nIndex scope is configured separately from tool defaults. Use `[index]`\nsettings such as Mail `accounts` or Calendar `calendars` to control what is\nstored locally; use `[defaults]` settings to control what MCP tools use when\nthe caller omits a scope.\n\n### Codex CLI\n\nRegister one or both servers:\n\n```bash\ncodex mcp add mail -- mac-mail-mcp serve --watch\ncodex mcp add calendar -- mac-calendar-mcp serve --watch\n```\n\nConfirm the registrations:\n\n```bash\ncodex mcp list\ncodex mcp get mail\ncodex mcp get calendar\n```\n\n### Claude Code\n\nCreate or edit `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"mail\": {\n      \"command\": \"mac-mail-mcp\",\n      \"args\": [\"serve\", \"--watch\"]\n    },\n    \"calendar\": {\n      \"command\": \"mac-calendar-mcp\",\n      \"args\": [\"serve\", \"--watch\"]\n    }\n  }\n}\n```\n\nWatch mode keeps the indexes current while the MCP servers are running. Mail\nuses file watching; Calendar performs a startup sync and then refreshes when\nCalendar's local SQLite database files change.\n\nFor global Claude Code configuration, put the same `mcpServers` object in\n`~/.claude/mcp.json`.\n\n## Development\n\nThis repository is organized as a `uv` workspace. Each MCP server lives under\n`packages/` with its own package metadata, source, tests, and README.\n\n```bash\ngit clone https://github.com/wagamama/apple-app-mcp\ncd apple-app-mcp\nuv sync\n\n# All packages\nuv run ruff check packages/mac-mail-mcp/src packages/mac-calendar-mcp/src\nuv run pytest\n\n# Individual packages\nuv run --package mac-mail-mcp pytest packages/mac-mail-mcp/tests\nuv run --package mac-calendar-mcp pytest packages/mac-calendar-mcp/tests\n```\n\nBuild distributions:\n\n```bash\nuv build --package mac-mail-mcp\nuv build --package mac-calendar-mcp\n```\n\n## Documentation\n\n- Shared agent instructions: [`AGENTS.md`](AGENTS.md)\n- Mail domain notes: [`MAIL.md`](MAIL.md)\n- Calendar domain notes: [`CALENDAR.md`](CALENDAR.md)\n- MCP client setup guide: [`docs/mcp-client-setup.md`](docs/mcp-client-setup.md)\n- Calendar implementation plan: [`docs/superpowers/plans/2026-05-30-mac-calendar-mcp-implementation.md`](docs/superpowers/plans/2026-05-30-mac-calendar-mcp-implementation.md)\n\nDocs are deployed with GitHub Pages from `.github/workflows/docs.yml`. The\nrepository must have Pages configured once in **Settings -> Pages -> Build and\ndeployment -> Source: GitHub Actions**. The workflow deploys the built artifact;\nit does not try to create or enable the Pages site because GitHub rejects that\noperation from the default workflow token in some repositories.\n\n## Acknowledgements\n\nThis codebase is derived from\n[`imdinu/apple-mail-mcp`](https://github.com/imdinu/apple-mail-mcp). Credit and\nthanks go to the original authors and contributors for the Apple Mail MCP\nfoundation this repository builds on.\n\n## License\n\nGPL-3.0-or-later\n",
  "bytes": 3920,
  "sha": "99c35e32894ea5849aff688c01925a0b91c3c85716bb4abf5528cd096366262f",
  "repo_slug": "wagamama/apple-app-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wagamama_mac_mail_mcp_8ecd6647/readme"
}