jons-mcp-imessage

Local MCP server to query and send iMessages on macOS, enabling AI assistants to read history and send messages.

python

3

GitHub Stars

python

Language

4 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": {
    "jonmmease-jons-mcp-imessage": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jons-mcp-imessage",
        "jons-mcp-imessage"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

You run a local MCP server that enables AI assistants to read your iMessage history and send messages from macOS. It exposes tools through the Model Context Protocol (MCP), so you can query conversations, read messages, and initiate sends from your AI workflows while keeping control on your machine.

How to use

To use this MCP server, start it locally and connect to it with an MCP client or your Claude-like workflow. The server runs on your machine and talks to Messages.app to read iMessages and to send messages via AppleScript. You can search messages, inspect conversations, and perform careful, permission-guarded actions from your AI assistant.

How to install

Prerequisites you need to prepare before you install and run the server.

# Clone the repository
git clone <your-repo-url>
cd jons-mcp-imessage

# Install with uv
uv pip install -e .

Additional setup and usage notes

You can start the server locally with a single command. The recommended runtime is the uvx-based workflow shown below. You can also integrate with Claude Code or Claude Desktop using the provided configuration examples.

uv run jons-mcp-imessage

Configure integration with Claude tools

To register the MCP server with Claude Code, run the following command.

# Register the MCP server with Claude Code
claude mcp add jons-mcp-imessage -- uv run --directory /path/to/jons-mcp-imessage jons-mcp-imessage

Claude Desktop configuration example

Add this JSON block to Claude Desktop configuration to connect to the MCP server.

{
  "mcpServers": {
    "jons-mcp-imessage": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jons-mcp-imessage",
        "jons-mcp-imessage"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

OpenAI API key note

If you have an OpenAI API key for semantic search, set the OPENAI_API_KEY environment variable in Claude Desktop’s config. If you do not have a key, you can still use keyword search.

Available tools

check_permissions

Verify database access and diagnose permission issues.

list_conversations

List all conversations with metadata such as participants and last message.

get_conversation_messages

Retrieve messages from a specific conversation by contact or chat_id.

get_recent_messages

Fetch the most recent messages across all conversations.

get_message_context

Get messages surrounding a specific message within the same thread.

search_messages

Search messages by text with optional filters like sender or date.

search_contacts

Search for contacts or handles by phone number or email in the iMessage database.

lookup_contact

Look up a contact name from the Contacts app using a phone number or email (requires Contacts permission).

send_message

Send a message to an existing conversation via Messages.app (requires Automation permission).