Apple Contacts MCP

Local-first MCP server for safely searching, editing, and maintaining Apple Contacts notes 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, notes, or add email/phone values. Dry-run by default.
• append_contact_note: append a dated interaction log entry to a contact note. 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.

Contact Notes

Use append_contact_note for CRM-style interaction logs instead of overwriting the full note field.

Input:

{
  "contactId": "CONTACT-ID-FROM-search_contacts",
  "date": "2026-06-04",
  "summary": "Met at an AI founder dinner. They are interested in local-first agent tooling.",
  "openThreads": [
    "Send the GitHub repo",
    "Follow up about a demo next week"
  ],
  "dryRun": true
}

The appended note entry uses:

- 2026-06-04 - Met at an AI founder dinner. They are interested in local-first agent tooling.
  Open threads: Send the GitHub repo; Follow up about a demo next week

An actual append requires:

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

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