iMessage

An MCP server that uses AppleScript to send iMessages and manage contacts.

javascript

25

GitHub Stars

javascript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run an MCP server on macOS that uses AppleScript to control Messages and Contacts, exposing contact lookup and iMessage sending as MCP actions. It runs locally on your machine, keeping data private while letting you interact with your contacts and send messages through your iMessage account.

How to use

Use this MCP server with your MCP client to look up contacts and send iMessages. Practical tasks you can perform include showing all contacts, searching by name or number, and sending messages to a person or a phone number. Messages are sent through your local Messages app and you will receive a confirmation when a message is sent.

How to install

Prerequisites you need before installing: macOS (for Messages and Contacts integration) and Node.js 18 or higher.

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

# 1) Install dependencies
npm install

# 2) Build the server
npm run build

# 3) Configure Claude Desktop to use the server (example path)
# On macOS, Claude Desktop expects a JSON config like this:
# Path: ~/Library/Application Support/Claude/claude_desktop_config.json
# Replace /path/to/imessage-server with your actual build output path

Additional sections

Configuration and security notes summarize how to run and trust the server locally.

To run Claude Desktop with this MCP server, use the following configuration snippet. It points Claude Desktop to the local server built from this project.

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

Security notes

All operations occur locally on your machine. No contact or message data is sent to external servers. You must grant macOS permissions for Contacts access and Messages access to use this MCP server. Messages are sent through your iMessage account on your device.

Troubleshooting

If messages aren’t sending, verify you are signed into Messages, ensure the required permissions are granted, and check the logs for errors.

# View Claude-related MCP logs to troubleshoot
tail -f ~/Library/Logs/Claude/mcp*.log

Available tools

search_contacts

Find contacts by name, phone, or email. Takes a search query and returns matching contacts by scanning names, phone numbers, and email addresses.

send_message

Send an iMessage to a recipient (phone or email). Provides the message content and returns confirmation or error details.