macos-mcp

MCP servers for macOS native apps — gives Claude Code, Claude Desktop, and any MCP client native access to Mail, Numbers, and Contacts.

No API keys, no OAuth, no cloud services. Talks directly to macOS apps via AppleScript. Runs locally on your Mac.

Servers

Mail (mailappmcp) — 21 tools

Works with every email account configured in Mail.app — iCloud, Gmail, Outlook, Fastmail, you name it.

Numbers (numbersmcp) — 29 tools

Works with any open Numbers spreadsheet.

Contacts (contactsmcp) — 15 tools

Works with the system address book — all accounts synced to Contacts.app.

Requirements

• macOS (uses AppleScript — won't work on Linux/Windows)
• Node.js 18+

Install

From npm

npm install -g mailappmcp    # Mail server
npm install -g numbersmcp    # Numbers server
npm install -g contactsmcp   # Contacts server

From source

git clone https://github.com/aernouddekker/macos-mcp.git
cd macos-mcp
npm install
npm run build

Configure

Claude Code

Add to ~/.claude/settings.json or your project's .mcp.json:

{
  "mcpServers": {
    "mailappmcp": {
      "command": "npx",
      "args": ["-y", "mailappmcp"]
    },
    "numbersmcp": {
      "command": "npx",
      "args": ["-y", "numbersmcp"]
    },
    "contactsmcp": {
      "command": "npx",
      "args": ["-y", "contactsmcp"]
    }
  }
}

Claude Desktop / Cowork

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mailappmcp": {
      "command": "npx",
      "args": ["-y", "mailappmcp"]
    },
    "numbersmcp": {
      "command": "npx",
      "args": ["-y", "numbersmcp"]
    },
    "contactsmcp": {
      "command": "npx",
      "args": ["-y", "contactsmcp"]
    }
  }
}

How it works

Each server runs locally over stdio. Tools build AppleScript strings, execute them via osascript, and parse the structured output back into JSON for the MCP response. A shared package (@mailappmcp/shared) provides the AppleScript runner, string escaping, and delimiter-based parsing.

Safety

• compose-message opens a visible draft — you review before sending
• send-message is a separate, explicit action
• reply-to-message and forward-message default to draft mode (sendImmediately: false)
• delete-messages moves to Trash (standard Mail.app behavior)

Known limitations

• content contains searches in AppleScript can be slow on large mailboxes — Mail server searches subject and sender by default
• osascript has a 30-second timeout per call
• Apps must be running (or will be auto-launched by AppleScript)
• Numbers tools require an open document

License

MIT