Skip to content
MCP server

Apple Contacts

MCP server to search and manage macOS Contacts and resolve message recipients

Runs locallyStatus and history
Install
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-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "apple-contacts-mcp": {
      "command": "uvx",
      "args": [
        "apple-contacts-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "apple-contacts-mcp": {
      "command": "uvx",
      "args": [
        "apple-contacts-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers