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.
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.
- macOS with Contacts.app
- Node.js 18 or newer
- Contacts/Automation permissions when macOS prompts
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.
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.
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.
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.
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.
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
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.
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
}
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.
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.
MIT