Apple Contacts
MCP server to search and manage macOS Contacts and resolve message recipients
- Pricing
- Open source
- Platforms
- macOS, CLI
- Runs
- Locally
- Version
- 1.1.7
- Listing updated
- today
Similar MCP servers
About Apple Contacts
Apple Contacts is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.
Built to run before any message is sent: give it a name, phone number or email and it returns the contact that matches, so an agent can confirm the right person before Messages or Mail is used. It is a standalone server, split out from an all-in-one Apple server for contact-only workflows.
By default it reads and writes through the native contacts framework using a small Swift helper that compiles on first use with Xcode Command Line Tools, so it does not wait for Contacts.app. An AppleScript backend remains available and is the one that supports contact notes. Name searches use Contacts.app's filtered lookup, and phone searches understand extension suffixes.
Three safety modes, safe_readonly, safe_manage and full_access, set what it may change, with safe_manage as the default. The README advises passing explicit phone or email arrays only when you mean to replace the existing set.
Install
Run in a terminal
claude mcp add apple-contacts-mcp -- uvx apple-contacts-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"apple-contacts-mcp": {
"command": "uvx",
"args": [
"apple-contacts-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"apple-contacts-mcp": {
"command": "uvx",
"args": [
"apple-contacts-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"apple-contacts-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"apple-contacts-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"apple-contacts-mcp": {
"command": "uvx",
"args": [
"apple-contacts-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"apple-contacts-mcp": {
"command": "uvx",
"args": [
"apple-contacts-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
APPLE_CONTACTS_MCP_SAFETY_MODESafety mode for Contacts operations: safe_readonly, safe_manage, or full_access.
Tools this server provides (7)
Taken from the project documentation; the running server may differ.
- search_tools
- Lists available tools for context-constrained clients.
- get_tool_info
- Returns details for one tool.
- contacts_find_duplicates
- Finds duplicate contacts.
- contacts_suggest_merge_candidates
- Suggests contacts that could be merged.
- contacts_health
- Reports Contacts authorization status without requesting access.
- contacts_permission_guide
- Explains how to grant Contacts access.
- contacts_recheck_permissions
- Rechecks permissions after a macOS change.
What it does
- Contact search
- Looks up contacts by name, organisation, phone or email.
- Recipient resolution
- Turns a name into a message-ready phone number or email.
- Edit contacts
- Creates, updates and deletes contacts and their labelled methods.
- Duplicate detection
- Finds duplicates and suggests merge candidates.
- Safety modes
- Choose read-only, manage or full access.
- Permission checks
- Health and permission guide tools for macOS access.
Good for
- Resolve a name to a phone number before sending a message
- Find duplicate contacts in the address book
- Update a contact's email or phone labels
- Check who owns a phone number or email
- Clean up the address book through an assistant
Pricing
Open source
Apple Contacts FAQ
Which platform does it need?
macOS; it needs Contacts access and Python 3.11+ when run from a clone.
How do I run it?
Use uvx apple-contacts-mcp from PyPI.
Can it be made read-only?
Yes, set APPLE_CONTACTS_MCP_SAFETY_MODE to safe_readonly.
Does it support notes on contacts?
Only with the AppleScript backend; the native backend rejects a nonempty note.
What if access is blocked?
Call contacts_permission_guide, then contacts_recheck_permissions.
Is Apple Contacts free?
Yes. Apple Contacts is open source, so you can use and self-host it for free.
How do I add Apple Contacts to Claude Code?
Run this command in your terminal: claude mcp add apple-contacts-mcp -- uvx apple-contacts-mcp
What are the best alternatives to Apple Contacts?
The closest alternatives to Apple Contacts are Ha MCP, Concord MCP, note1, InviteKit Calendar Files and Google Workspace MCP.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.
