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

A new open-source tool called Apple Contacts MCP enables local AI agents to search, edit, and maintain Apple Contacts on macOS through a local-first MCP server. The server uses AppleScript automation and macOS privacy prompts instead of cloud credentials, with write operations set to dry-run by default and requiring explicit user confirmation. This allows AI assistants like Claude and Codex to interact with a user's local contact database while maintaining privacy and user control over changes.

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