home / mcp / macos contacts mcp server

macOS Contacts MCP Server

MCP server for native macOS Contacts integration via AppleScript. Search, view, and manage contacts directly through AI assistants like Claude Desktop and Cursor.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jcontini-macos-contacts-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/macos-contacts-mcp/build/index.js"
      ]
    }
  }
}

You connect your macOS Contacts data to AI assistants so you can search, view, and manage contacts directly from conversations. This MCP server lets your assistant read and modify your local Contacts app without syncing to external services, making contact management fast and private.

How to use

Your AI assistant can perform practical tasks with your macOS Contacts data. You can search for contacts by name or company, view full contact details including emails and phones, and browse recent changes. You can add new contacts with notes and social profiles, update existing contacts with new information, and ask to see contact details in context during a conversation. These actions all stay local to your machine and don’t require syncing to cloud services.

How to install

Prerequisites you need before installation:

Node.js installed (any recent version)
npm installed (comes with Node.js)
An MCP-compatible AI assistant

Step-by-step commands to set up the MCP server on your machine:

git clone https://github.com/jcontini/macos-contacts-mcp.git
cd macos-contacts-mcp
npm install && npm run build

Configuration and usage details

You will run the server locally and connect it to your MCP client. The example configuration shows how to expose the server to your MCP client using a stdio connection that runs the server script directly with Node.js.

{
  "mcpServers": {
    "macos-contacts": {
      "command": "node",
      "args": ["/path/to/your/macos-contacts-mcp/build/index.js"]
    }
  }
}

After adding the server configuration, restart your MCP-enabled assistant so it can load the new connection. You should then be able to ask questions like, “Find my contacts at Google” or “Show me John's contact details.”

Security and permissions

macOS will prompt you to grant access to Contacts and Automation when you first use the features. You can also grant permissions manually in System Settings → Privacy & Security → Contacts and Automation to ensure smooth operation.

Troubleshooting

If you see errors like "Contact not found," verify that the contact exists in your Contacts app with the exact name you searched for. If you encounter permission issues, double-check the macOS privacy settings to ensure your assistant has Access to Contacts and Automation. If the server won’t start, confirm that you ran the installation and build steps exactly as shown and that the path in your MCP config points to the correct build/index.js file.

Notes on usage and capabilities

Social media and contact details can be stored and updated for each contact, including LinkedIn, Twitter, GitHub, and other websites. You can query recent changes to see who you added or updated within a specific period.

Future improvements

Plans for easier distribution include desktop extensions, npm-based usage with NPX, and MCP directory listings to help you discover and install MCP servers quickly.

Available tools

searchContacts

Search contacts by name or company and return matching results from your local Contacts app.

viewContactDetails

Provide full details for a selected contact, including emails, phones, and social links.

addContact

Add a new contact with basic fields and optional social profiles.

updateContact

Update an existing contact with new information or social links.

browseRecentContacts

List contacts that were added or updated recently to help you track changes.