home / mcp / apple mail mcp server

Apple Mail MCP Server

Provides fast access to Apple Mail data via MCP, including batched email fetching and a fast full-text search index.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "imdinu-apple-mail-mcp": {
      "command": "apple-mail-mcp",
      "args": [
        "--watch"
      ],
      "env": {
        "APPLE_MAIL_INDEX_PATH": "~/.apple-mail-mcp/index.db",
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

Apple Mail MCP provides a fast MCP server for accessing Apple Mail data. It delivers batched email fetching and a full-text search index to speed up operations like body searches, making it easier to build clients that manage and search your Apple Mail messages.

How to use

You connect your MCP client to the Apple Mail MCP server by configuring an MCP server entry that points to the apple-mail-mcp command. This server exposes common MCP endpoints to list accounts, list mailboxes, fetch emails, retrieve full content for a message, and perform searches.

How to install

Prerequisites you need before installation:

1) Install Python tooling on your system.

2) Ensure you have a tool runner available to install and run Python utilities.

Install the Apple Mail MCP package using the recommended installer.

pipx install apple-mail-mcp

Add to your MCP client configuration:
```
{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp"
    }
  }
}
```

Optionally, you can start a watch mode to keep monitoring for changes:
```
apple-mail-mcp index --verbose
```

Notes:
- The quick start uses the command `apple-mail-mcp` as the MCP server executable. 
- The example MCP client configuration shows the server named `mail` with the command set to `apple-mail-mcp`. 
- The index command may require Full Disk Access for Terminal on some systems.

Additional content

Configuration details you may use when running the server in your environment include default account, default mailbox, and the index location. The following example demonstrates how to customize the server behavior via environment variables and arguments.

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

# Optional environment variable notes
# APPLE_MAIL_DEFAULT_ACCOUNT defines the default email account used by the server.
# APPLE_MAIL_INDEX_PATH defines where the index database is stored, defaulting to `~/.apple-mail-mcp/index.db` if not set.

Available tools

list_accounts

List all configured email accounts in Apple Mail.

list_mailboxes

List mailboxes for a given account (or all if none specified).

get_emails

Retrieve emails with optional filters such as unread, flagged, or date ranges, with an optional limit.

get_email

Fetch the full content of a single email by its message identifier.

search

Search emails by query across scope options like all, subject, sender, or body.