Apple Contacts MCP

Local-first MCP server for safely searching and editing Apple Contacts on macOS.

The server uses Contacts.app automation through AppleScript today. That keeps install simple and uses macOS privacy prompts instead of cloud credentials. Writes are dry-run by default and require explicit confirmation.

Tools

• contacts_status: check Contacts.app access and return aggregate counts.

• search_contacts: search local contacts by name, organization, job title, email, or phone.

• create_contact: create a contact. Dry-run by default.

• update_contact: update scalar fields or add email/phone values. Dry-run by default.

• delete_contact: delete a contact. Dry-run by default and requires a confirmation phrase.

• test_roundtrip: create, edit, verify, and delete one dummy contact.

Requirements

• macOS with Contacts.app

• Node.js 18 or newer

• Contacts/Automation permissions when macOS prompts

Quick Start

git clone https://github.com/lu-wo/apple-contacts-mcp.git
cd apple-contacts-mcp
node ./bin/apple-contacts-mcp.cjs

The command starts an MCP stdio server. Most users should install it through an MCP-capable agent rather than running it directly.

Install In Codex

From this repo:

codex mcp add apple-contacts -- node /absolute/path/to/apple-contacts-mcp/bin/apple-contacts-mcp.cjs

Then start a new Codex thread so the MCP tools are loaded.

Install In Other MCP Clients

Add a stdio MCP server with:

{
  "mcpServers": {
    "apple-contacts": {
      "command": "node",
      "args": ["/absolute/path/to/apple-contacts-mcp/bin/apple-contacts-mcp.cjs"]
    }
  }
}

For Claude Desktop, add the server under the mcpServers object in the Claude Desktop config file and restart Claude Desktop.

Write Safety

Create, update, and delete operations are dry-run by default. An actual write must pass both:

{
  "dryRun": false,
  "confirm": true
}

Delete also requires:

{
  "confirmPhrase": "delete contact"
}

This gives agents a natural two-step flow: propose the change first, then apply only after user approval.

Privacy

This server runs locally on your Mac. It does not call a cloud API or upload contacts on its own. Your agent will still see whatever contact data you ask the MCP server to return, so use field filters and redaction when possible.

Contacts may sync through iCloud, Google, Exchange, or another configured account. A local write can propagate to those services.

Current Backend

The first backend is AppleScript automation of Contacts.app. A future backend may use a signed Swift helper around Apple's Contacts.framework for more structured access.

Direct SQLite writes to ~/Library/Application Support/AddressBook are intentionally not supported.

License

MIT