Apple Contacts — Claude Code MCP server: search macOS contacts
Lets an AI client read and search Apple Contacts on macOS, then turn a match into a recipient ready for a message.
claude mcp add --env APPLE_CONTACTS_MCP_SAFETY_MODE=<APPLE_CONTACTS_MCP_SAFETY_MODE> --transport stdio applecontacts-mcp -- uvx apple-contacts-mcpWhat Apple Contacts does
The server runs on your Mac and hands the client tools for looking up entries in Contacts. One of them resolves a person into a recipient you can drop straight into an email or a text. Handy when the agent needs to reach someone and you don't have the address at hand.
You need macOS and Python 3.11+. Startup goes through uvx apple-contacts-mcp, so install uv first — the command fails without it. Safety behaviour comes from APPLE_CONTACTS_MCP_SAFETY_MODE; a blank or invalid value falls back to safe_readonly. Access to Contacts itself is granted by you in the macOS prompt or System Settings. Nothing approves it on your behalf.
stdio is the default transport. Streamable HTTP needs APPLE_<DOMAIN>_MCP_TRANSPORT=streamable-http plus the host and port variables, and the bind is limited to 127.0.0.1, ::1 or localhost — these servers have no remote authentication and reject network or wildcard binds. Putting one behind a tunnel or public proxy is out. Whatever the server returns may travel on to your model provider, and Apple apps sync through iCloud, so local execution does not keep the data local.
What it helps with
- look up a contact when you don't have the exact address
- resolve a person into a message recipient
- confirm someone exists in Contacts before sending
- expose only contacts to the agent, not mail or calendar
Example prompts for the agent
- Find Maria Sokolova in Contacts and show me her email address
- Resolve the recipient for the contract email and verify the address through Contacts
- Search Contacts for the surname Reed and tell me the phone number
How to install Apple Contacts
Platform CLI
claude mcp add --env APPLE_CONTACTS_MCP_SAFETY_MODE=<APPLE_CONTACTS_MCP_SAFETY_MODE> --transport stdio applecontacts-mcp -- uvx apple-contacts-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-contacts-mcp <command>
Platform CLI
codex mcp add applecontacts-mcp --env APPLE_CONTACTS_MCP_SAFETY_MODE=<APPLE_CONTACTS_MCP_SAFETY_MODE> -- uvx apple-contacts-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-contacts-mcp <command>
Config file
{
"mcpServers": {
"applecontacts-mcp": {
"command": "uvx",
"args": [
"apple-contacts-mcp"
],
"env": {
"APPLE_CONTACTS_MCP_SAFETY_MODE": "<APPLE_CONTACTS_MCP_SAFETY_MODE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-contacts-mcp <command>
Config file
{
"servers": {
"applecontacts-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"apple-contacts-mcp"
],
"env": {
"APPLE_CONTACTS_MCP_SAFETY_MODE": "<APPLE_CONTACTS_MCP_SAFETY_MODE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-contacts-mcp <command>
Platform CLI
gemini mcp add -e APPLE_CONTACTS_MCP_SAFETY_MODE=<APPLE_CONTACTS_MCP_SAFETY_MODE> applecontacts-mcp uvx apple-contacts-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-contacts-mcp <command>
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 apple-contacts-mcp -- uvx apple-contacts-mcp. Restart the client afterwards.
What does Apple Contacts do?
It searches and inspects entries in Apple Contacts on macOS, and can turn a match into a recipient ready for sending.
What does the server need to run?
macOS and Python 3.11+, plus uv installed, since startup uses uvx. You approve Contacts access yourself in the macOS prompt.
