imessage-mcp-server

MCP.Pizza Chef: marissamarym

The imessage-mcp-server is an MCP server that leverages AppleScript to interface with macOS Messages and Contacts applications. It enables sending iMessages and managing contacts through the Model Context Protocol, providing a TypeScript server wrapper for seamless integration. Users can view and search contacts locally, send messages to phone numbers or emails, and receive delivery confirmations. All data remains on the user's machine, ensuring privacy and security. This server is ideal for automating iMessage communication and contact management within macOS environments.

Use This MCP server To

Send iMessages programmatically from macOS Search and retrieve macOS contacts via MCP Automate contact management on macOS Confirm message delivery status in workflows Integrate iMessage sending into AI assistants

README

iMessage MCP Server

⚠️ DISCLAIMER - USE AT YOUR OWN RISK ⚠️

This software is provided as-is, without any warranties or guarantees.

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

This server uses AppleScript to interface with macOS Messages and Contacts apps through the Model Context Protocol (MCP). It wraps AppleScript commands in a TypeScript server to allow you to:

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

Features

Resources

  • Access your contacts via contacts://all
  • View contact details including names, phone numbers, and email addresses
  • All data stays local on your machine

Tools

  • search_contacts - Find contacts by name, phone, or email

    • Takes a search query and returns matching contacts
    • Searches across names, phone numbers, and email addresses
  • send_message - Send an iMessage

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

Installation

  1. Install dependencies:
npm install
  1. Build the server:
npm run build
  1. 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"]
    }
  }
}
  1. Restart Claude Desktop

  2. Grant permissions when prompted for:

    • Contacts access
    • Messages access

Usage

Once installed, you can talk to Claude Desktop naturally:

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

Security Notes

  • All operations happen locally on your machine
  • No contact or message data is sent to external servers
  • The server requires macOS permissions for Contacts and Messages access
  • Messages are sent through your iMessage account

Development

For development and debugging, use the MCP Inspector:

npx @modelcontextprotocol/inspector node build/server.js

Requirements

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

Troubleshooting

If messages aren't sending:

  1. Check Messages app is signed in
  2. Verify permissions are granted
  3. Look for errors in Claude Desktop logs:
tail -f ~/Library/Logs/Claude/mcp*.log

imessage-mcp-server FAQ

How does imessage-mcp-server send messages?
It uses AppleScript to control the macOS Messages app, sending iMessages through the MCP server interface.
Is my contact data sent to external servers?
No, all contact and message data stays local on your macOS machine for privacy and security.
Can I search contacts by phone number or email?
Yes, the server supports searching contacts by name, phone number, or email address.
What platforms does imessage-mcp-server support?
It only supports macOS since it relies on AppleScript to interact with native Messages and Contacts apps.
How do I receive confirmation that a message was sent?
The server provides confirmation responses after sending messages via the send_message tool.
Is there any warranty or guarantee for this server?
No, the software is provided as-is without warranties or guarantees.
Can this server be integrated with LLMs like OpenAI, Claude, or Gemini?
Yes, it can be integrated as an MCP server to provide iMessage capabilities to LLM-powered applications.
What programming language is used for the server?
The server is implemented in TypeScript, wrapping AppleScript commands for macOS integration.