Installation¶

Claude Code Plugin¶

claude plugin marketplace add imdinu/apple-mail-mcp
claude plugin install apple-mail@imdinu

The plugin registers the MCP server automatically via a thin launcher that runs the released PyPI package (uvx → pipx → private venv, whichever is available on your machine).

Claude Desktop Bundle¶

Download apple-mail-mcp-<version>.mcpb from the latest release and double-click it. Claude Desktop installs and registers the server; the bundle uses the same launcher as the Claude Code plugin.

Both surfaces launch the server with --watch, so the index is kept current as mail arrives. That background sync reads ~/Library/Mail/, which needs Full Disk Access on the app that launches the server (Claude Code or Claude Desktop): System Settings → Privacy & Security → Full Disk Access. Then run apple-mail-mcp index once from a terminal that also has Full Disk Access to enable body search — see Getting Started.

With pipx¶

pipx install apple-mail-mcp

The FTS5 search index (~/.apple-mail-mcp/index.db) is keyed to your home directory, not the install method — every install surface above shares the same index. A persistent install just avoids the small per-launch resolution overhead of ephemeral runners like pipx run or uvx.

With uv¶

uv tool install apple-mail-mcp

With pip¶

pip install apple-mail-mcp

From Source¶

For development or to run the latest unreleased version:

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync

Run with:

uv run apple-mail-mcp

Prerelease Versions¶

To install a prerelease (e.g., v0.2.0a1):

pipx install apple-mail-mcp --pip-args='--pre'
# or
uv tool install apple-mail-mcp --prerelease=allow

Verify Installation¶

apple-mail-mcp status

This prints the index status. If you see output (even "no index found"), the installation is working.

Requirements¶