macOS Contacts MCP
Supports storing and managing Facebook profiles for contacts in the macOS Contacts app.
Supports storing and managing GitHub profiles for contacts in the macOS Contacts app.
Enables interaction with the macOS Contacts app, allowing users to search, view, add, and update contacts with details including emails, phones, social links, and notes.
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., "@macOS Contacts MCP Find John Smith's contact details and social links"
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.
macOS Contacts for MCP
Connect your macOS Contacts app to AI assistants like Claude Desktop and Cursor. Search, view, and manage your contacts directly through conversations using your local Contacts data.
What This Does
Search your contacts by name or company
View full contact details including emails, phones, and social links
Add new contacts with notes, social media profiles (LinkedIn, Twitter, GitHub, etc.)
Update existing contacts with new information and social links
Browse recent contacts to see who you've added or modified
Works with your local macOS Contacts app - no need to sync with external services.
Related MCP server: MCP Google Contacts Server
Setup Instructions
1. Get the Code
git clone https://github.com/jcontini/macos-contacts-mcp.git
cd macos-contacts-mcp
npm install && npm run build2. Add to Your AI Assistant
Add this configuration to your MCP client:
{
"mcpServers": {
"macos-contacts": {
"command": "node",
"args": ["/path/to/your/macos-contacts-mcp/build/index.js"]
}
}
}3. Grant Permissions
When you first use the contacts features, macOS will ask for permission:
Contacts Access: Allow your AI assistant to access Contacts
Automation Permission: Allow the app to control Contacts
You can also set these manually in System Settings → Privacy & Security → Contacts and Automation.
4. Restart Your Assistant
Close and reopen your AI assistant to load the new connection.
Using It
Once set up, you can ask your AI assistant things like:
"Find my contacts at Google"
"Show me John's contact details and social links"
"Add a new contact for Jane Smith with her LinkedIn profile"
"Who did I add to contacts this week?"
"Update John's job title and add his GitHub profile"
Social Media Support
You can store and manage social media profiles for contacts:
LinkedIn profiles
Twitter/X accounts
GitHub profiles
Facebook profiles
Any other websites or social links
Troubleshooting
"Contact not found" errors: Make sure the contact exists in your Contacts app with the exact name you're searching for.
Permission errors: Check System Settings → Privacy & Security and make sure your AI assistant has access to Contacts and Automation.
Server won't start: Make sure you ran npm install && npm run build and the path in your configuration is correct.
Requirements
macOS with the Contacts app
Node.js (any recent version)
An MCP-compatible AI assistant
Works with Claude Desktop, Cursor, and any other app that supports the Model Context Protocol.
Future Plans
We're working on easier distribution methods to eliminate the need for manual installation:
Desktop Extensions (.dxt)
Claude Desktop now supports one-click installation via Desktop Extensions. We plan to package this server as a .dxt file for:
No manual setup - double-click to install
No dependencies - Claude Desktop includes Node.js runtime
Automatic updates - seamless version management
Curated directory - discover through Claude Desktop's extension marketplace
NPM Distribution
For developers who prefer package managers:
NPX support:
npx macos-contacts-mcpfor instant usageGlobal installation:
npm install -g macos-contacts-mcpVersion management: Easy updates via npm
MCP Directory Listings
We're submitting to major MCP directories for better discoverability:
Glama.ai - Comprehensive MCP marketplace with quality ratings
PulseMCP - Clean directory with 5000+ servers and filters
McpServers.org - Community-driven MCP server registry
Awesome MCP Servers - GitHub-based curated list
These improvements will make installation as simple as a single click or command while maintaining the same powerful local contact management capabilities.
TODO: LLM-Friendly Improvements
Based on real-world usage with LLMs, the following improvements would make this MCP more robust:
Graceful Error Handling
Issue: AppleScript syntax errors don't provide helpful feedback to LLMs about what went wrong
Solution: Catch AppleScript errors and translate them into actionable error messages
Why: Better error messages help LLMs understand and retry with corrected inputs
Available Tools
5 toolscreate_contactC
Create a new contact
Inputs: name (required), organization, job_title, emails, +3 more.
get_contactB
Get full contact details by name or ID
Inputs: identifier (required).
get_recent_contactsC
Get contacts created or modified within a date range
Inputs: days_back, type, limit.
search_contactsC
Search for contacts by name, organization, or notes
Inputs: query, limit.
update_contactC
Update an existing contact
Inputs: identifier (required), name, organization, job_title, +4 more.
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 clearly distinct purpose with no overlap: create, get by ID/name, get by recency, search by attributes, and update. The descriptions make it unambiguous which tool to use for each operation, preventing misselection.
All tools follow a consistent verb_noun pattern (e.g., create_contact, get_contact, search_contacts) with no deviations in style or casing. This predictability makes the tool set easy to navigate and understand.
With 5 tools, this server is well-scoped for managing contacts on macOS, covering essential operations without bloat. Each tool earns its place, providing a focused and efficient interface for the domain.
The tool set covers most core CRUD operations (create, get, update) and useful queries (search, recent), but lacks a delete_contact tool, which is a minor gap. Agents can still handle the domain effectively, though deletion would complete the lifecycle.
Maintenance
Related MCP Connectors
Connect Apple iCloud and Microsoft 365 mail, calendars, contacts and tasks to AI.
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
An AI-first personal CRM you run in natural language: contacts, reminders, notes, and more.
A private address book your AI can search, update and import into.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to read iMessage history and send messages on macOS. Supports conversation listing, message search with keyword and semantic modes, contact lookup, and sending messages to existing conversations.1311MIT
- AlicenseNot gradedqualityDmaintenanceGives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage contacts with full CRUD, dedup, merge, import/export, sync with Google/Apple/CardDAV, and git-backed rollback.AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI to control Apple Mac apps like Messages, Notes, Contacts, Mail, Reminders, Calendar, and Maps through natural language commands.MIT