Imessage

🚀 iMessage MCP Server

This is an MCP server that uses AppleScript to send iMessages and manage contacts. The server interfaces with the macOS Messages and Contacts applications through AppleScript via the Model Context Protocol (MCP). It wraps AppleScript commands in a TypeScript server, enabling you to:

• View and search your contacts.
• Send iMessages to contacts or phone numbers.
• Get confirmation when messages are sent.

⚠️ Important Note

Use at your own risk. This software is provided as is, without any warranty or guarantee.

✨ Features

Resources

• Access your contacts via contacts://all.
• View contact details, including names, phone numbers, and email addresses.
• All data is stored locally on your computer.

Tools

• search_contacts - Search for contacts by name, phone, or email.

  • Accepts a search query and returns matching contacts.
  • Searches in names, phone numbers, and email addresses.

• send_message - Send an iMessage.

  • Accepts a recipient (phone/email) and message content.
  • Sends the message through your local Messages app.
  • Returns confirmation or error details.

📦 Installation

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Configure Claude Desktop to use the server: On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

4. Restart Claude Desktop.
5. Grant permissions when prompted:
   • Contacts access.
   • Messages access.

💻 Usage Examples

Basic Usage

After installation, you can talk to Claude Desktop naturally:

• "Show my contacts."
• "Search for contacts named Marissa."
• "Send a message to 555-0123 saying I'll be there in 10 minutes."
• "Send an iMessage to Alice asking if lunch is still on."

🔧 Technical Details

Security Considerations

• All operations are performed on your local computer.
• No contact or message data is sent to external servers.
• The server requires macOS permissions to access Contacts and Messages.
• Messages are sent through your iMessage account.

Development

For development and debugging, use the MCP monitor:

npx @modelcontextprotocol/inspector node build/server.js

Requirements

• macOS (for Messages and Contacts integration).
• Node.js 18 or higher.
• Claude Desktop.
• An activated iMessage account.

Troubleshooting

If messages are not sent:

1. Check if the Messages app is logged in.
2. Verify that permissions have been granted.
3. Check the error in the Claude Desktop logs:

tail -f ~/Library/Logs/Claude/mcp*.log