Apple Contacts

Apple Contacts MCP

MCP server for Apple Contacts on macOS.

Provides access to contacts for lookup, search, and recipient resolution. Use before sending messages to resolve names into phone numbers or email addresses.

When to use

• Contact-only workflows
• Recipient validation before messaging
• Contact lookup separated from the all-in-one server

What It Does

• List and search contacts
• Full contact detail lookup
• Message recipient resolution
• Tool discovery helpers search_tools and get_tool_info for context-constrained clients
• Create, update, and delete contacts
• Duplicate detection and merge-candidate suggestions (contacts_find_duplicates, contacts_suggest_merge_candidates)
• Phone number and email method editing with labels
• Directory resources and recipient-check prompts
• Health and permission checks: contacts_health, contacts_permission_guide, contacts_recheck_permissions

Install On This Mac

Quick start (uvx, from PyPI)

With uv installed:

uvx apple-contacts-mcp

No clone, no venv management.

From a clone

git clone https://github.com/JonathanRReed/Apple-MCPs.git

cd Apple-MCPs uv sync --all-packages

This builds one workspace environment with every server's entry point in .venv/bin (for example .venv/bin/apple-contacts-mcp). You can also point an MCP client at AppleContacts-MCP/start.sh, which prefers uv run and falls back to a plain venv bootstrap (Python 3.11+ required).

Install In AI Agents

Generic MCP client config

{

"mcpServers": { "apple-contacts": { "command": "uvx", "args": ["apple-contacts-mcp"], "env": { "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage" } } } }

Running from a clone instead? Use /path/to/Apple-MCPs/AppleContacts-MCP/start.sh as the command with empty args.

Claude Code example

claude mcp add --transport stdio --scope user apple-contacts -- uvx apple-contacts-mcp

--scope user makes the server available in every project. To share it with one repository through its .mcp.json instead, use --scope project.

Safety Modes

• safe_readonly
• safe_manage
• full_access

Transport

stdio is the default and recommended transport. Set APPLE_CONTACTS_MCP_TRANSPORT=streamable-http (with optional APPLE_CONTACTS_MCP_HOST and APPLE_CONTACTS_MCP_PORT) to serve Streamable HTTP instead.

Search Behavior

Name and organization searches use Contacts.app's filtered lookup. A no-match name returns an empty result without scanning the whole address book. Phone queries with a numeric/punctuation base, including recognized extension suffixes (ext, ext., extension, extn., x, #, and ;ext=) and an optional tel: prefix, retain the paginated directory fallback for method-value matching. Email queries containing @ retain it too. Extension matching keeps the base number and extension separate, requires the exact extension, and allows local-number suffix matching. Recipient resolution chooses the matching phone method and rejects multiple distinct matching methods.

Literal control characters and complex emoji returned by Contacts are decoded on the Python side without changing their text.

macOS Permissions

• Contacts access is required
• contacts_health reads native authorization status without requesting access or reading contacts. permission_status distinguishes authorized, unknown, denied, and failed checks. The AppleScript backend reports unknown authorization without sending Apple Events. Explicit Contacts operations retain their permission checks.

Launch Checklist

• Add uvx apple-contacts-mcp (or a clone's AppleContacts-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Contacts tool surface is loaded into context
• Call contacts_health first
• If Contacts access is blocked, call contacts_permission_guide
• After changing macOS permissions, call contacts_recheck_permissions

Prompting Notes

• tools/list returns the full Contacts tool surface. Context-constrained clients can use search_tools first, then get_tool_info for the Contacts tool they need.
• Run Contacts before any iMessage or Mail action when the user gives a person name.
• Resolve by name, phone number, or email before acting.
• If multiple contacts match, confirm the intended person before sending.
• When updating a person, pass explicit phones or emails arrays only when you intend to replace that method set.
• Keep a labeled phone or email on the contact before routing Messages or Mail through it.

Related

• Apple-Tools-MCP

Native Contacts access

Contacts uses CNContactStore by default, so reads and writes do not wait for Contacts.app. First use compiles the packaged Swift helper with Xcode Command Line Tools and caches a signed application bundle, Apple Contacts MCP Helper, under ~/.apple-mcps/build. Set APPLE_CONTACTS_MCP_HELPER_BUILD_DIR to choose another build directory. If the app running the MCP server already has Contacts access, it is used. Otherwise macOS asks whether Apple Contacts MCP Helper may access Contacts. See Calendar, Reminders and Contacts: who macOS asks about.

Set APPLE_CONTACTS_MCP_BACKEND=applescript to use the previous backend. The native backend returns first and last names directly and preserves phone/email update semantics: omit a collection to keep it, or pass [] to clear it. Contact notes require a separate macOS entitlement; a nonempty note is rejected before a native write. The AppleScript backend remains available for notes.

The helper also answers lookup_handles (a JSON array of phone numbers or email addresses) with the contacts that could own them, in one pass over the directory. Unlike the other commands it never asks for access: without a grant it returns PERMISSION_DENIED or AUTHORIZATION_UNKNOWN. AppleContactsBridge.lookup_handles applies the phone_matching exact-owner rules to that set, and Apple-Tools-MCP uses it to name Messages handles, only when the helper is already built. It is not exposed as an MCP tool.

The native helper compiles an immutable source snapshot into a bundle named by its full SHA-256 hash. A source change during compilation is rejected, and a concurrent build cannot replace an installed bundle. Different source versions keep separate executables with the same bundle identifier. The helper is ad-hoc signed, so macOS may ask once more after an update that changes its source.

The native helper is adapted from Jaume Puig's work in JaumeAP/Apple-MCPs.