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 project apple-contacts -- uvx apple-contacts-mcp

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.

macOS Permissions

  • Contacts access is required
  • contacts_health reports whether Contacts access is currently available

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

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for JonathanRReed from gravatar.com JonathanRReed

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

mcp model-context-protocol macos apple ai-agent automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apple_contacts_mcp-1.0.1.tar.gz (20.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

apple_contacts_mcp-1.0.1-py3-none-any.whl (21.5 kB view details)

Uploaded Python 3

File details

Details for the file apple_contacts_mcp-1.0.1.tar.gz.

File metadata

  • Download URL: apple_contacts_mcp-1.0.1.tar.gz
  • Upload date:
  • Size: 20.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for apple_contacts_mcp-1.0.1.tar.gz
Algorithm Hash digest
SHA256 d8b0b1504d16481f9f07a2c198fd700c5edd8b0d4b40581254ce58990ee92afe
MD5 42c64acbfcf4480e5494b1cff0a2aba1
BLAKE2b-256 8d82df4c39751a640232f3a549325265713368e453edc873a57e1c0b5157f285

See more details on using hashes here.

Provenance

The following attestation bundles were made for apple_contacts_mcp-1.0.1.tar.gz:

Publisher: release.yml on JonathanRReed/Apple-MCPs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apple_contacts_mcp-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for apple_contacts_mcp-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 daf24cc37821f43c6f22dc3cd1ac6cf4697b236cd8cf8e45becc06154a3012c7
MD5 10fe584db4831d551a10831931c0a66b
BLAKE2b-256 865d1dba86b0ca63fbbf7650387c3431320b56ae171f4e239af6c1212fb665cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for apple_contacts_mcp-1.0.1-py3-none-any.whl:

Publisher: release.yml on JonathanRReed/Apple-MCPs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page