imessage

This MCP server provides a bridge between Claude Desktop and your macOS Messages and Contacts apps by wrapping AppleScript calls in a Node.js server. It exposes two main tools: search_contacts, which lets you look up contacts by name, phone number, or email, and send_message, which sends an iMessage to a recipient using your local Messages app. All data stays on your device, and operations run with the permissions granted to macOS applications (Contacts and Messages). You can invoke these tools through natural Claude prompts like asking to show contacts, searching for a contact, or sending a message to a phone number or email.

Prerequisites:

• macOS with Access to Messages and Contacts
• Node.js 18 or higher installed on the Mac
• Claude Desktop installed

Install and build:

npm install

npm run build

Configure Claude Desktop to use the server. On macOS, add or edit the config file at:

~/Library/Application Support/Claude/claude_desktop_config.json

Example configuration snippet:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-server/build/server.js"]
    }
  }
}

Restart Claude Desktop after saving the config. When prompted, grant macOS permission for Contacts access and Messages access to allow the server to interact with your apps.

Usage after installation remains via Claude Desktop prompts, such as: "Show me my contacts" or "Send a message to 555-0123 saying I'll be there in 10 minutes".

Notes and tips:

• All operations run locally on your Mac; no data is sent externally.
• Ensure the macOS AppleScript permissions are granted for Contacts and Messages; without these, actions may fail.
• The server relies on the Messages app being signed into an iMessage account and accessible via the Messages app.
• If you modify paths or use a different build location, update the CLI config accordingly.
• For development and debugging, you can run the inspector with:

  npx @modelcontextprotocol/inspector node build/server.js