Skip to main content
Glama
Apple Contacts MCP

Apple Contacts MCP

by lu-wo

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.

Related MCP server: contacts-mcp

Requirements

  • macOS with Contacts.app

  • Node.js 18 or newer

  • Contacts/Automation permissions when macOS prompts

Quick Start

git clone <repo-url>
cd apple-contacts-mcp
npm test
npm run smoke

npm run smoke verifies the MCP handshake and tool list without touching Contacts.

To run a live dummy create/edit/note/delete roundtrip:

npm run smoke:live

macOS may prompt for Contacts or Automation permissions. The live smoke test creates one dummy contact, edits it, appends a note, verifies the change, and deletes the dummy.

Install For Your Agent

This is a stdio MCP server. Any MCP-capable agent needs the same command:

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

Use an absolute path. Relative paths are easy to break when an agent launches MCP servers from another working directory.

Install In Codex

After cloning:

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

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

To confirm the server is registered:

codex mcp list

Ask Codex:

Use apple-contacts to run contacts_status.

Install In Claude Desktop

Open the Claude Desktop config file on macOS:

open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Add this under the top-level mcpServers object, then restart Claude Desktop:

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

If the file already has other MCP servers, add only the apple-contacts entry inside the existing mcpServers object.

Ask Claude:

Use the Apple Contacts MCP server to run contacts_status. Do not show any contact values.

Install In Other Agents

Add a stdio MCP server with:

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

If your agent has an MCP CLI, use its equivalent of:

<agent> mcp add apple-contacts -- node /absolute/path/to/apple-contacts-mcp/bin/apple-contacts-mcp.cjs

Good first prompt for any agent:

Install this repository as a local MCP server named apple-contacts. Use the absolute path to bin/apple-contacts-mcp.cjs, then restart or reload your MCP tools and run contacts_status. Treat contact data as personal data and keep writes dry-run unless I explicitly approve them.

Permissions

This server automates Contacts.app locally. The first live call may trigger macOS permission prompts for Contacts and/or Automation. Approve those prompts for the terminal or app that is launching the MCP server.

If a call fails because Contacts.app is not running, open Contacts and retry:

open -a Contacts

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

Available Tools

6 tools
contacts_statusContacts StatusA

Check Apple Contacts access and return aggregate counts without exposing contact values.

Inputs: no named parameters.

create_contactCreate ContactA

Create an Apple Contact. Dry-run by default; actual writes require dryRun=false and confirm=true.

Inputs: firstName, lastName, organization, jobTitle, +6 more.

delete_contactDelete ContactA

Delete an Apple Contact by contactId. Dry-run by default and requires confirmPhrase='delete contact'.

Inputs: contactId (required), dryRun, confirm, confirmPhrase.

search_contactsSearch ContactsB

Search Apple Contacts by name, organization, job title, email, or phone.

Inputs: query (required), limit, includeEmails, includePhones, +1 more.

test_roundtripTest Contacts RoundtripA

Create, edit, verify, and delete one dummy contact. Requires confirm=true.

Inputs: confirm.

update_contactUpdate ContactA

Update an Apple Contact by contactId. Dry-run by default; actual writes require dryRun=false and confirm=true.

Inputs: contactId (required), changes (required), dryRun, confirm.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct operation: status check, create, delete, search, roundtrip test, and update. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., create_contact, search_contacts), with only 'contacts_status' varying slightly but still adhering to the pattern.

    Tool Count5/5

    Six tools is an appropriate and focused set for managing Apple Contacts, covering core operations without unnecessary bloat.

    Completeness5/5

    The tool surface covers CRUD operations (create, search/read, update, delete) plus a status check and a roundtrip test for validation. No obvious gaps for the domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local MCP server that exposes Apple Contacts data, enabling phone, email, and name lookups via a helper app.
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Local MCP server for macOS native apps: Mail, Calendar, Reminders, Notes, Messages, and Contacts. Enables reading and organizing your Mac life through a single stdio process using AppleScript/JXA.
      40
      1
      MIT