Configuration¶

Apple Mail MCP is configured via environment variables. All settings have sensible defaults — no configuration is required to get started.

Environment Variables¶

Variable	Default	Description
`APPLE_MAIL_DEFAULT_ACCOUNT`	First account	Default email account for all tools
`APPLE_MAIL_DEFAULT_MAILBOX`	`INBOX`	Default mailbox when none specified
`APPLE_MAIL_INDEX_PATH`	`~/.apple-mail-mcp/index.db`	SQLite index database location
`APPLE_MAIL_INDEX_MAX_EMAILS`	unset	Optional per-mailbox ceiling (default: uncapped)
`APPLE_MAIL_INDEX_STALENESS_HOURS`	`24`	Hours before index is considered stale
`APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES`	`Drafts`	Comma-separated mailboxes to skip in search
`APPLE_MAIL_READ_ONLY`	`false`	When `true`, disables any write operations

Per-Mailbox Email Limit (Optional)¶

By default the index covers every email in every mailbox — there is no per-mailbox cap. Set APPLE_MAIL_INDEX_MAX_EMAILS to opt in to a ceiling, useful if you want to bound index size on machines with many large mailboxes:

export APPLE_MAIL_INDEX_MAX_EMAILS=10000
apple-mail-mcp rebuild

When a cap is set and a mailbox exceeds it, the most recent emails by file modification time are kept. apple-mail-mcp rebuild reports how many mailboxes hit the cap, and apple-mail-mcp status surfaces the same information after the fact.

MCP Client Configuration¶

Claude Desktop¶

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work",
        "APPLE_MAIL_DEFAULT_MAILBOX": "INBOX"
      }
    }
  }
}

Claude Code¶

Edit .mcp.json in your project root or ~/.claude/mcp.json globally:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

With Real-Time Indexing¶

To keep the search index automatically updated:

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

CLI Commands¶

apple-mail-mcp              # Run MCP server (default)
apple-mail-mcp serve        # Run MCP server explicitly
apple-mail-mcp serve -r     # Run in read-only mode
apple-mail-mcp --watch      # Run with real-time index updates
apple-mail-mcp index        # Build search index from disk
apple-mail-mcp status       # Show index statistics
apple-mail-mcp rebuild      # Force rebuild index
apple-mail-mcp search       # Search emails (JSON output)
apple-mail-mcp read         # Read a single email (JSON output)
apple-mail-mcp emails       # List emails (JSON output)
apple-mail-mcp accounts     # List accounts (JSON output)
apple-mail-mcp mailboxes    # List mailboxes (JSON output)
apple-mail-mcp extract      # Extract attachment (JSON output)
apple-mail-mcp integrate claude  # Generate a Claude Code skill file

Read-Only Mode¶

Use --read-only (or -r) on the serve command to prevent any write operations. This can also be set via the APPLE_MAIL_READ_ONLY environment variable.

apple-mail-mcp serve --read-only

Or via environment variable:

export APPLE_MAIL_READ_ONLY=true
apple-mail-mcp serve

Index Location¶

The FTS5 index database is stored at ~/.apple-mail-mcp/index.db by default. Override with:

export APPLE_MAIL_INDEX_PATH="/path/to/custom/index.db"

The database file is created with 0600 permissions (owner read/write only) for security.