macOS Contacts
MCP server for native macOS Contacts integration via AppleScript. Search, view, and manage contacts directly through AI assistants like Claude Desktop and Cursor.
What is macOS Contacts?
macOS Contacts is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server for native macos contacts integration via applescript. search, view, and manage contacts directly through ai assistants like claude desktop and cursor.
MCP server for native macOS Contacts integration via AppleScript. Search, view, and manage contacts directly through AI assistants like Claude Desktop and Cursor.
This server falls under the File Systems category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- MCP server for native macOS Contacts integration via AppleSc
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx macos-contactsConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use macOS Contacts
The macOS Contacts MCP Server integrates the native macOS Contacts app with AI assistants like Claude Desktop and Cursor via AppleScript. It allows you to search contacts by name or company, retrieve full contact details including emails, phone numbers, and social media profiles, create new contacts with notes, update existing entries, and view recently modified contacts — all through natural language. No external API keys or cloud services are required; the server reads and writes directly to your local Contacts database.
Prerequisites
- macOS with the native Contacts app installed and populated
- Node.js 18 or higher installed
- npm installed alongside Node.js
- Claude Desktop or Cursor AI as your MCP-compatible client
- Contacts access permission granted to Terminal/your shell when prompted by macOS
Clone the repository
Clone the macos-contacts-mcp repository to a stable location on your Mac. Avoid placing it in a temporary directory as the MCP config will reference this path permanently.
git clone https://github.com/jcontini/macos-contacts-mcp.git
cd macos-contacts-mcpInstall dependencies and build
Install the npm dependencies and compile the TypeScript source. This creates the build/ directory containing the runnable index.js file.
npm install && npm run buildVerify the build output
Confirm that build/index.js was created successfully. This is the file you will reference in your MCP client configuration.
ls build/
# Should show: index.jsAdd to Claude Desktop configuration
Edit your Claude Desktop config file to add the macos-contacts server. Use the absolute path to the built index.js file. On macOS the config is at ~/Library/Application Support/Claude/claude_desktop_config.json.
Grant Contacts access permission
When Claude Desktop first attempts to use the contacts server, macOS will prompt you to grant Contacts access. Click 'OK' to allow. You can verify and manage this permission in System Settings → Privacy & Security → Contacts.
Test the integration
Ask Claude to search for a contact you know exists in your Contacts app. This verifies the full pipeline from MCP client through AppleScript to the Contacts database.
macOS Contacts Examples
Client configuration
Claude Desktop configuration for macOS Contacts. Replace the path with the actual absolute path to your cloned repository.
{
"mcpServers": {
"macos-contacts": {
"command": "node",
"args": ["/absolute/path/to/macos-contacts-mcp/build/index.js"]
}
}
}Prompts to try
These queries map to search, create, update, and retrieve contact tools exposed by the server.
- "Find all my contacts who work at Stripe."
- "What is the phone number and email for John Smith in my contacts?"
- "Add a new contact: Jane Doe, [email protected], LinkedIn: linkedin.com/in/janedoe."
- "Show me the contacts I've added or modified in the last 7 days."
- "Update the Twitter handle for Alex Chen to @alexchen."Troubleshooting macOS Contacts
AppleScript errors or 'not authorized to send Apple events' message
Go to System Settings → Privacy & Security → Automation and ensure that your terminal app (or Claude Desktop) has permission to control Contacts. Also check System Settings → Privacy & Security → Contacts. You may need to remove and re-add the permission if it was previously denied.
npm run build fails with TypeScript errors
Ensure you ran 'npm install' first to install all dependencies including the TypeScript compiler. If errors persist, check your Node.js version with 'node --version' — Node 18 or higher is required. Try deleting node_modules and running npm install again.
Claude cannot find the MCP server after config changes
Verify the path in your config is absolute (starts with /Users/...) and points directly to build/index.js, not the directory. Fully quit Claude Desktop using Cmd+Q and relaunch — simply closing the window does not reload the config.
Frequently Asked Questions about macOS Contacts
What is macOS Contacts?
macOS Contacts is a Model Context Protocol (MCP) server that mcp server for native macos contacts integration via applescript. search, view, and manage contacts directly through ai assistants like claude desktop and cursor. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install macOS Contacts?
Follow the installation instructions on the macOS Contacts GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with macOS Contacts?
macOS Contacts works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is macOS Contacts free to use?
Yes, macOS Contacts is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
macOS Contacts Alternatives — Similar File Systems Servers
Looking for alternatives to macOS Contacts? Here are other popular file systems servers you can use with Claude, Cursor, and VS Code.
Electerm
★ 14.1k📻Terminal/ssh/sftp/ftp/telnet/serialport/RDP/VNC/Spice client(linux, mac, win)
Plik
★ 1.8kPlik is a temporary file upload system (Wetransfer like) in Go.
Kordoc
★ 957An MCP server that parses South Korean document formats like HWP, HWPX, and PDF into Markdown. It features specialized table reconstruction and security-hardened extraction optimized for administrative and public institution files.
macOS Automator
★ 801A Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.
PDF Reader
★ 723Enables reading, searching, and metadata extraction from PDF files without loading the entire content into the context window. It provides efficient tools for text cleaning, page-specific extraction, and context-aware search results.
Filesystem MCP Server
★ 643Provides comprehensive filesystem operations (read, write, list, create, delete, move files and directories) through the Model Context Protocol with Streamable HTTP transport and built-in security through configurable root directory restrictions.
Browse More File Systems MCP Servers
Explore all file systems servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up macOS Contacts in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use macOS Contacts?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.