imessage-kit-mcp

iMessage Kit MCP Server

An MCP server for iMessage — read, send, and automate conversations via iMessage Kit.

Features

• Send Messages: Send iMessages to phone numbers or email addresses
• Read Messages: Retrieve message history from conversations
• List Conversations: Get all active iMessage conversations
• Conversation Details: Get detailed information about specific conversations
• Dual Transport: Supports both STDIO (local) and HTTP (production) transports

Tools

imsg_send_message

Sends an iMessage to a recipient.

Inputs:

• recipient (string, required): Phone number (e.g., '+1234567890') or email address
• text (string, required): Message text to send
• chatId (string, optional): Chat ID if continuing an existing conversation

imsg_read_messages

Reads messages from an iMessage conversation.

Inputs:

• chatId (string, optional): Chat/conversation ID
• recipient (string, optional): Recipient phone number or email
• limit (number, optional): Maximum number of messages (default: 50)
• offset (number, optional): Number of messages to skip (default: 0)

imsg_get_conversations

Gets a list of all iMessage conversations.

Inputs:

• limit (number, optional): Maximum number of conversations (default: 50)
• offset (number, optional): Number of conversations to skip (default: 0)

imsg_get_conversation_details

Gets detailed information about a specific conversation.

Inputs:

• chatId (string, required): Chat/conversation ID

Installation

Prerequisites

• Bun — required runtime
• macOS (required for iMessage functionality)

Install Dependencies

bun install

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

STDIO Transport (Local)

{
  "mcpServers": {
    "imessage-kit": {
      "command": "bun",
      "args": ["run", "/path/to/imessage-kit-mcp/src/index.ts"]
    }
  }
}

HTTP Transport

{
  "mcpServers": {
    "imessage-kit": {
      "command": "bun",
      "args": ["run", "/path/to/imessage-kit-mcp/src/index.ts", "--port", "3002"],
      "url": "http://localhost:3002/mcp"
    }
  }
}

Usage with VS Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [],
    "servers": {
      "imessage-kit": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/imessage-kit-mcp/src/index.ts"]
      }
    }
  }
}

Development

Running the Server

# STDIO transport (default)
bun run src/index.ts

# HTTP transport
bun run src/index.ts --port 3002

Testing with MCP Inspector

bunx @modelcontextprotocol/inspector src/index.ts

Project Structure

imessage-kit-mcp/
├── src/
│   ├── index.ts           # Main entry point
│   ├── server.ts          # MCP server implementation
│   ├── client.ts          # iMessage Kit SDK client wrapper
│   ├── config.ts          # Configuration management
│   ├── cli.ts             # CLI argument parsing
│   ├── types.ts           # TypeScript type definitions
│   ├── tools/
│   │   ├── index.ts       # Tool exports
│   │   └── imessage.ts    # iMessage tool definitions
│   └── transport/
│       ├── index.ts       # Transport exports
│       ├── stdio.ts       # STDIO transport
│       └── http.ts         # HTTP transport
├── package.json
├── tsconfig.json
└── README.md

Notes

• This server requires macOS to access iMessage functionality
• Requires Bun (uses bun:sqlite for native SQLite access)
• Uses iMessage Kit for database access
• Make sure you have proper permissions to access Messages on macOS