Configuration¶

This page covers the Mac Mail MCP config surface and the Mac Calendar MCP config surface. Both packages support environment variables and an optional TOML config file generated by their init command.

Mac Mail MCP¶

Mac Mail MCP can be configured via a TOML config file at ~/.mac-mail-mcp/config.toml, environment variables, or both. All settings have sensible defaults — no configuration is required to get started.

Quick start¶

Generate a commented config file:

mac-mail-mcp init

This writes ~/.mac-mail-mcp/config.toml with every available key documented inline. All values are commented out, so defaults remain in effect — uncomment what you want to override. Pass --force to overwrite an existing config file.

Configuration file¶

The TOML file at ~/.mac-mail-mcp/config.toml is loaded on every server start. All sections and keys are optional.

config_version = 1

[defaults]
# account = "Personal"          # Default email account
# mailbox = "INBOX"             # Default mailbox

[index]
# path = "~/.mac-mail-mcp/index.db"   # FTS5 database location
# max_emails = 5000             # Per-mailbox ceiling (omit for uncapped)
# staleness_hours = 24.0        # Hours before re-sync
# exclude_mailboxes = ["Drafts"]   # Mailboxes to skip during indexing

[server]
# read_only = false             # Disable write operations

Empty list semantics: exclude_mailboxes = [] explicitly means "no exclusions" — different from omitting the key, which uses the ["Drafts"] default.

Validation: malformed TOML, unknown keys, type mismatches, and config_version mismatches all raise a clear error with the file path and the offending key. The server refuses to start rather than silently using degraded config.

Environment variables¶

Every config key can also be set via an environment variable. Env vars override TOML file values, which is useful for per-deployment overrides in CI or in MCP client launch configs.

Precedence¶

When the same value is set in multiple places, the highest-precedence source wins. From highest to lowest:

1. CLI flags (e.g. mac-mail-mcp serve -r)
2. Environment variables (APPLE_MAIL_*)
3. TOML config file (~/.mac-mail-mcp/config.toml)
4. Built-in defaults

For multi-client deployments (Claude Desktop + Cursor + Cline + ...), the TOML file is the cleanest place for durable user policy — set it once instead of pasting the same env: {} block into every client.

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 (or [index] max_emails in config.toml) 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
mac-mail-mcp rebuild

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

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 or [server] read_only = true in config.toml.

mac-mail-mcp serve --read-only

Or via environment variable:

export APPLE_MAIL_READ_ONLY=true
mac-mail-mcp serve

When read-only mode is active, write-capable MCP tools raise PermissionError with a clear message rather than silently no-oping.

Index location¶

The FTS5 index database is stored at ~/.mac-mail-mcp/index.db by default. Override via the env var or TOML key:

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

[index]
path = "/path/to/custom/index.db"

The database file is created with 0600 permissions (owner read/write only) for security. The same posture applies to config.toml (created by mac-mail-mcp init) and the attachment cache.

MCP client configuration¶

Claude Desktop¶

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

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

If you have multiple MCP clients, consider setting durable defaults in ~/.mac-mail-mcp/config.toml instead, and keep the env block here for per-client overrides only.

Claude Code¶

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

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

With real-time indexing¶

To keep the search index automatically updated:

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

CLI commands¶

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

Mac Calendar MCP¶

Mac Calendar MCP can be configured via a TOML config file at ~/.mac-calendar-mcp/config.toml, environment variables, or both.

Generate a commented config file:

mac-calendar-mcp init

This writes ~/.mac-calendar-mcp/config.toml with every available key documented inline. All values are commented out, so defaults remain in effect. Pass --force to overwrite an existing config file.

config_version = 1

[defaults]
# calendars = ["Work", "Personal"]

[index]
# path = "~/.mac-calendar-mcp/index.db"
# staleness_hours = 24.0
# past_years = 5
# future_years = 1
# max_occurrences_per_series = 10000

Calendar config precedence is environment variables, then TOML config file, then built-in defaults. The generated config.toml is written with 0600 permissions.