mcpField
M
Mac Mail MCP

Mac Mail MCP

Local
github.com/wagamamaCommunication0Updated 15w ago
Repository

About Mac Mail MCP

Mac Mail MCP gives assistants access to local Apple Mail data, with disk-first reads and full-coverage FTS5 search across message bodies.

Key features

  1. 01Read local Apple Mail data
  2. 02Disk-first message reads
  3. 03FTS5 search across message bodies
  4. 04Watch files to update indexes

Use cases

  1. 01Search local email bodies
  2. 02Read Apple Mail data on demand
  3. 03Keep email search indexes current

MCP support

It exposes local Apple Mail reading and search to MCP clients. File watching can keep indexes updated while the server runs.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "wagamama-mac-mail": {
      "command": "uvx",
      "args": [
        "mac-mail-mcp"
      ]
    }
  }
}
Run commanduvx mac-mail-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypimac-mail-mcp0.5.15

Tools

8

Saved tool list · updated 2w ago

This tool takes no parameters.

Details

From the project README

Apple App MCP

Workspace for MCP servers that expose local Apple app data to assistants.

Packages

PackageStatusPurpose
mac-mail-mcpBetaMac Mail MCP server with disk-first reads and full-coverage FTS5 body search.
mac-calendar-mcpAlphaRead-only Mac Calendar MCP server with indexed archive search.

Quick Start

Install the package you want:

pipx install mac-mail-mcp
pipx install mac-calendar-mcp

Build local indexes for fast search:

mac-mail-mcp index --verbose
mac-calendar-mcp authorize
mac-calendar-mcp index

Calendar authorization installs a small helper app with a stable macOS privacy identity. Approve its Full Calendar Access prompt once so terminal, MCP, and scheduled launchd rebuilds can use EventKit consistently. EventKit runs inside that signed app identity; the Calendar MCP does not execute the helper's script through an anonymous osascript process.

Generate optional config files:

mac-mail-mcp init
mac-calendar-mcp init

Index scope is configured separately from tool defaults. Use [index] settings such as Mail accounts or Calendar calendars to control what is stored locally; use [defaults] settings to control what MCP tools use when the caller omits a scope.

Codex CLI

Register one or both servers:

codex mcp add mail -- mac-mail-mcp serve --watch
codex mcp add calendar -- mac-calendar-mcp serve --watch

Confirm the registrations:

codex mcp list
codex mcp get mail
codex mcp get calendar
Claude Code

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "mail": {
      "command": "mac-mail-mcp",
      "args": ["serve", "--watch"]
    },
    "calendar": {
      "command": "mac-calendar-mcp",
      "args": ["serve", "--watch"]
    }
  }
}

Watch mode keeps the indexes current while the MCP servers are running. Mail uses file watching; Calendar performs a startup sync and then refreshes when Calendar's local SQLite database files change.

For global Claude Code configuration, put the same mcpServers object in ~/.claude/mcp.json.

Development

This repository is organized as a uv workspace. Each MCP server lives under packages/ with its own package metadata, source, tests, and README.

git clone https://github.com/wagamama/apple-app-mcp
cd apple-app-mcp
uv sync

# All packages
uv run ruff check packages/mac-mail-mcp/src packages/mac-calendar-mcp/src
uv run pytest

# Individual packages
uv run --package mac-mail-mcp pytest packages/mac-mail-mcp/tests
uv run --package mac-calendar-mcp pytest packages/mac-calendar-mcp/tests

Build distributions:

uv build --package mac-mail-mcp
uv build --package mac-calendar-mcp

Documentation

Docs are deployed with GitHub Pages from .github/workflows/docs.yml. The repository must have Pages configured once in Settings -> Pages -> Build and deployment -> Source: GitHub Actions. The workflow deploys the built artifact; it does not try to create or enable the Pages site because GitHub rejects that operation from the default workflow token in some repositories.

Acknowledgements

This codebase is derived from imdinu/apple-mail-mcp. Credit and thanks go to the original authors and contributors for the Apple Mail MCP foundation this repository builds on.

License

GPL-3.0-or-later

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.