Apple Contacts · mgcrea — Claude Code MCP server: features and setup
This MCP server lets an agent look up people in the macOS address book and match phone numbers or email addresses to names. Contact changes stay hidden unless writes are enabled.
claude mcp add --env APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> --transport stdio contacts -- npx -y @mgcrea/mcp-apple-contactsWhat Apple Contacts does
Apple Contacts exposes tools for reading and finding address book entries. An agent can match a phone number or email address to a name, search contacts, list entries, and retrieve an individual record. When a match is uncertain, the server reports that state instead of choosing a person.
Creating and editing entries require APPLE_CONTACTS_ALLOW_WRITES=1. With that setting off, write tools are not exposed to the agent. macOS asks for Contacts access when the server reads the address book; approve the system prompt to proceed.
The server reads contacts stored on the Mac and handles more than one contact store. When writes are enabled, each change is saved and then read back. That matters because an edit can appear during a script run without having reached the address book store.
What it helps with
- Match a phone number to a contact name
- Identify the person behind an email address
- Search the macOS address book
- Retrieve a specific contact record
- Create or edit an entry with writes enabled
Example prompts for the agent
- Find the contact with the email address
[email protected]. - Match these phone numbers to names and show any ambiguous results.
- Create a contact named Alex with the phone number
+1....
How to install Apple Contacts
Platform CLI
claude mcp add --env APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> --transport stdio contacts -- npx -y @mgcrea/mcp-apple-contactsReplace <…> with your own values
Platform CLI
codex mcp add contacts --env APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> -- npx -y @mgcrea/mcp-apple-contactsReplace <…> with your own values
Config file
{
"mcpServers": {
"contacts": {
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-contacts"
],
"env": {
"APPLE_CONTACTS_ALLOW_WRITES": "<APPLE_CONTACTS_ALLOW_WRITES>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"contacts": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-contacts"
],
"env": {
"APPLE_CONTACTS_ALLOW_WRITES": "<APPLE_CONTACTS_ALLOW_WRITES>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> contacts npx -y @mgcrea/mcp-apple-contactsReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Apple Contacts
How do I install Apple Contacts in Claude Code?
Run claude mcp add mcp-apple-contacts -- npx -y @mgcrea/mcp-apple-contacts. This command adds the server for contact lookups.
What does Apple Contacts do?
It gives an agent access to contact search and read operations on macOS, including matching phone numbers and email addresses to names. Creating or editing entries requires writes to be enabled.
How can Apple Contacts create or edit entries?
Set APPLE_CONTACTS_ALLOW_WRITES=1 in the server configuration. The agent will then be able to use the contact creation and update tools.
Similar MCP servers
All MCP servers for Agent setup: memory, context, orchestration →Apple Contacts by other authors comes first.
