Show HN: Apple Contacts MCP – Local AI Access to macOS Contacts

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1 Commit

1 Commit

.codex-plugin

.codex-plugin

bin

bin

docs

docs

scripts

scripts

skills/apple-contacts

skills/apple-contacts

tests

tests

.gitignore

.gitignore

.mcp.json

.mcp.json

LICENSE

LICENSE

README.md

README.md

package.json

package.json

Repository files navigation

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 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:

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

About

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

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

JavaScript 100.0%