Mac Mail MCP

io.github.wagamamaPublished by GitHub account wagamamav0.5.15Updated Oct 24, 2026

Mac Mail MCP server with full-coverage FTS5 body search for local Apple Mail.

VerifiedSTDIODesktop onlyFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

A local MCP server that gives an assistant disk-first access to Apple Mail on a Mac, with full-coverage FTS5 body search over a local index.

What you can do
Read local Apple Mail data from disk and search message bodies through a full-coverage FTS5 index built on the machine. Build and refresh the local index, including a watch mode that keeps it current while the server runs. Generate optional config files and set index scope separately from tool defaults, so stored data and default tool scope can differ. Register the server with MCP clients such as Codex CLI or Claude Code.
When to use it
Use it when you want an assistant on a Mac to search and read your local Apple Mail archive, especially large mailboxes where fast full-text body search matters, and you are comfortable building a local index of that mail.
Requirements
Runs as a local process on macOS only, installed from PyPI (mac-mail-mcp, for example with pipx or uvx) and started with the serve command. A local index must be built first. No authentication, environment variables or headers are declared.
Before you install
It reads your local Apple Mail data and stores an index of message contents on disk, so index scope settings decide what is copied locally. The README describes the package as Beta. Watch mode keeps reading mail files while the server runs.

Installation

In SourceWeft

  1. Open Mac Mail MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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:

bash
pipx install mac-mail-mcppipx install mac-calendar-mcp

Build local indexes for fast search:

bash
mac-mail-mcp index --verbosemac-calendar-mcp authorizemac-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:

bash
mac-mail-mcp initmac-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:

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

Confirm the registrations:

bash
codex mcp listcodex mcp get mailcodex mcp get calendar

Claude Code

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

json
{  "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.

bash
git clone https://github.com/wagamama/apple-app-mcpcd apple-app-mcpuv sync
# All packagesuv run ruff check packages/mac-mail-mcp/src packages/mac-calendar-mcp/srcuv run pytest
# Individual packagesuv run --package mac-mail-mcp pytest packages/mac-mail-mcp/testsuv run --package mac-calendar-mcp pytest packages/mac-calendar-mcp/tests

Build distributions:

bash
uv build --package mac-mail-mcpuv 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

Source: README.md at commit a82211a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.15LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts