contacts-mcp
Exposes Apple Contacts data, allowing lookup of contacts by phone, email, name, or identifier.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@contacts-mcp find John Doe's email address"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
contacts-mcp
Local MCP server that exposes Apple Contacts data through a Contacts.framework helper app.
Built entirely by OpenAI GPT-5.4 via Codex.
Install
git clone https://github.com/<your-account>/contacts-mcp.git
cd contacts-mcp
./bootstrap.shRelated MCP server: Apple Contacts MCP
Run
npm run startPermissions
Run contacts_permissions once with prompt: true.
The helper app is intended to be built with the project's normal code signing so macOS can attribute Contacts access to a stable app identity.
If the prompt does not appear from inside Codex, launch the helper app directly once:
open ContactsMCPHelperApp/build/Build/Products/Release/ContactsMCPHelperApp.appWhen opened directly, the app will request Contacts access and show a status alert. After that initial grant, the MCP tools can read visible contacts normally.
Lookup behavior is intentionally narrow: contacts_lookup_phone, contacts_lookup_email, and contacts_search_name return zero or more ranked matches, contacts_get_contact fetches one unified contact by identifier, and the server does not expose any write path.
Phone lookup uses the framework predicate first, then falls back to canonical digit matching when needed. Email lookup uses the framework predicate first, then falls back to exact case-insensitive comparison. Name search uses the framework name predicate first, then backfills ranked matches across full name, nickname, organization, and component fields when needed.
MCP config
{
"mcpServers": {
"contacts": {
"command": "node",
"args": ["/absolute/path/to/contacts-mcp/dist/index.js"],
"env": {
"CONTACTS_MCP_HELPER_APP_PATH": "/absolute/path/to/contacts-mcp/ContactsMCPHelperApp/build/Build/Products/Release/ContactsMCPHelperApp.app"
}
}
}
}Verify
npm run verifyAvailable Tools
5 toolscontacts_get_contactGet ContactARead-only
Fetch one Apple Contact by unified contact identifier.
Inputs: contactIdentifier (required).
contacts_lookup_emailLookup EmailARead-only
Resolve one email address to matching Apple Contacts entries. Returns zero or more ranked matches.
Inputs: emailAddress (required), maxResults.
contacts_lookup_phoneLookup PhoneBRead-only
Resolve one phone number to matching Apple Contacts entries. Returns zero or more ranked matches.
Inputs: phoneNumber (required), maxResults.
contacts_permissionsContacts PermissionsA
Check and optionally prompt for Apple Contacts access used by the helper app.
Inputs: prompt.
contacts_search_nameSearch NameBRead-only
Search Apple Contacts by name, nickname, or organization. Returns zero or more ranked matches.
Inputs: nameQuery (required), maxResults.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct query modality: permission check, lookup by phone, lookup by email, fetch by ID, and search by name. No two tools overlap in input type or purpose, so misselection is unlikely.
All names use snake_case with a consistent `contacts_` prefix, and four of five follow a verb_noun pattern. `contacts_permissions` is a slight noun-form deviation but remains predictable.
Five tools is well-scoped for a read-focused Contacts helper: permissions, three query modalities, and one ID fetch. Each tool has a clear role and none feels redundant.
The surface covers access check and all common read paths (ID, phone, email, name). It lacks any list-all/browse operation or mutation tools, but those may be outside the stated read-lookup scope; core retrieval is covered.
Maintenance
Related MCP Connectors
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Identity resolution MCP server for phone/email lookups across 31+ services. Global + India coverage.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA macOS app that provides an MCP server to your Messages, Contacts, and more1,977MIT
- AlicenseAqualityDmaintenanceLocal-first MCP server for safely searching and editing Apple Contacts on macOS via AppleScript automation, with dry-run writes and explicit confirmation.65MIT
- AlicenseBqualityBmaintenanceMCP server for the Infomaniak Contacts API, enabling listing and searching contacts across address books.293 npm3MIT
- FlicenseNot gradedqualityDmaintenanceLocal MCP server for macOS Messages + Contacts: send messages, read chat history, wait for replies, and manage Contacts.app entries.1-