iMessage MCP Server

An enterprise-grade Model Context Protocol (MCP) Server for macOS iMessage integration over Streamable HTTP and SSE transports.

It connects your local Mac's iMessage database (~/Library/Messages/chat.db), macOS Contacts (AddressBook), and Swift/AppleScript automation capabilities directly to AI assistants (Antigravity, Claude Desktop, Cursor, Gemini CLI, etc.) running locally or over secure tunnels (Cloudflare Tunnel, Tailscale).

Features

• Dual MCP Transports: Supports modern Streamable HTTP (/mcp) and Server-Sent Events (/sse).

• Full-Text Message Search: Instant SQLite query across historical iMessage text and rich attributed bodies.

• Contact Resolution: Integrates with macOS Contacts database (AddressBook-v22.abcddb) to resolve names, phone numbers, and emails.

• Multimodal Attachment Reading: Exposes attachment metadata (MIME type, size, path) and automatically converts .heic photos to .jpg for vision-capable LLMs.

• Single-Bubble Attachment Sending: Swift NSPasteboard + System Events paste pipeline that combines text and file attachments into a single message bubble without triggering "Not Delivered" sandboxing failures.

• Group Chat Rosters: Inspects group conversation member lists and handles.

• Bearer Token Auth: Secures all MCP endpoints behind customizable Bearer token authentication.

Related MCP server: jons-mcp-imessage

Architecture Overview

┌─────────────────────────┐          HTTP/SSE           ┌──────────────────────────────┐
│  AI Assistant / Client  │  ─────────────────────────> │   iMessage MCP Server        │
│  (Claude, Antigravity)  │  <Authorization: Bearer>   │   (Node.js / Express / TS)   │
└─────────────────────────┘                             └──────────────┬───────────────┘
                                                                       │
                                                                       ▼
                                                        ┌──────────────────────────────┐
                                                        │   macOS iMessage CLI         │
                                                        │   (bin/imessage python script)│
                                                        └──────────────┬───────────────┘
                                                                       │
                         ┌─────────────────────────────────────────────┼────────────────────────────────────────────┐
                         ▼                                             ▼                                            ▼
           ┌──────────────────────────┐                  ┌──────────────────────────┐                 ┌──────────────────────────┐
           │ Messages DB (Read-Only)  │                  │ Contacts DB (Read-Only)  │                 │ Messages.app Automation  │
           │ ~/Library/Messages/chat.db│                  │ AddressBook-v22.abcddb   │                 │ Swift NSPasteboard + GUI │
           └──────────────────────────┘                  └──────────────────────────┘                 └──────────────────────────┘

Prerequisites

• Host Machine: macOS 12 (Monterey), 13 (Ventura), 14 (Sonoma), or 15 (Sequoia).

• Node.js: >=24.0.0 (Active LTS).

• Package Manager: pnpm (npm install -g pnpm).

• Python: Python 3.9+ (built-in macOS python3 or Homebrew).

• Messages App: Signed into an active Apple ID / iMessage account.

Installation & Setup Guide

1. Clone & Install Dependencies

git clone https://github.com/genericService/imessage-mcp-server.git
cd imessage-mcp-server
pnpm install

2. Configure Environment & Bearer Token

Create a .env file in the project root:

cp .env.example .env

Edit .env to set your desired port and a strong random Bearer token:

PORT=8765
AUTH_TOKEN=your-secure-random-bearer-token-here
USE_HTTPS=false

3. Grant macOS TCC & System Permissions

Due to macOS privacy safeguards (TCC), the process executing the server requires Full Disk Access and Accessibility permissions.

A. Full Disk Access (Required to read chat.db)

1. Open System Settings → Privacy & Security → Full Disk Access.

2. Enable the toggle for Terminal (or sshd-daemon if running remotely over SSH).

B. Accessibility & Automation (Required for sending attachments)

1. Open System Settings → Privacy & Security → Accessibility.

2. Click +, press Cmd + Shift + G, paste /usr/libexec/sshd-keygen-wrapper (or your Terminal app path), and click Open.

3. Ensure the toggle switch is turned ON.

4. Open System Settings → Privacy & Security → Automation and ensure Terminal / sshd has permission to control System Events and Messages.

4. Build & Start Server

# Build TypeScript
pnpm build

# Run in production mode
pnpm start

Client Configuration (mcp_config.json)

To connect an AI client (Antigravity, Cursor, Claude Desktop, etc.) to the iMessage MCP server:

1. Native Direct HTTP Transport (Recommended)

Modern MCP clients support direct HTTP / SSE transport definitions with custom headers (Bearer token & Cloudflare Access tokens) without any external bridge process:

{
  "mcpServers": {
    "imessage": {
      "url": "https://imessage.genericservice.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN",
        "CF-Access-Client-Id": "YOUR_CLIENT_ID.access",
        "CF-Access-Client-Secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

2. Local Network (Direct HTTP)

{
  "mcpServers": {
    "imessage": {
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

3. Legacy mcp-remote Stdio Bridge (Optional)

If your client only supports stdio command execution:

{
  "mcpServers": {
    "imessage": {
      "command": "pnpm",
      "args": [
        "dlx",
        "mcp-remote",
        "https://imessage.genericservice.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_AUTH_TOKEN"
      ],
      "trust": true
    }
  }
}

OAuth 2.0 Auth Server (CLI & Online Agents)

The server embeds a native OAuth 2.0 Authorization Server supporting RFC 8414 metadata, Client Credentials grant, and Authorization Code grant with PKCE for CLI tools (Claude Code, Antigravity CLI, Codex) and online services (ChatGPT Actions, custom GPTs, web apps).

1. Server Metadata Endpoint

• Discovery URL: https://imessage.genericservice.app/.well-known/oauth-authorization-server

• Authorization Endpoint: https://imessage.genericservice.app/oauth/authorize

• Token Endpoint: https://imessage.genericservice.app/oauth/token

2. Client Credentials Token Exchange (CLI & Headless Agents)

Agents can exchange client_id and client_secret for a signed HS256 JWT access token:

curl -X POST https://imessage.genericservice.app/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "antigravity-cli",
    "client_secret": "YOUR_SERVICE_SECRET"
  }'

Returns:

{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ref_5ae1f64eb91...",
  "scope": "imessage:all"
}

3. Interactive Web & Online Agents (ChatGPT / Web Apps)

1. Point your client to https://imessage.genericservice.app/oauth/authorize.

2. The user sees a branded authorization consent screen on the Mac host.

3. Upon approval, the server redirects with an authorization code exchanged at /oauth/token.

Available MCP Tools

Security & Local Action Audit Logging

To maintain absolute privacy and trauma-informed data autonomy, the server never stores or logs personal message text, passwords, or attachment bytes.

If you wish to log AI agent action executions for security auditing, set ENABLE_AUDIT_LOG=true in your .env file. This appends structured JSON audit lines to logs/audit.log:

{
  "timestamp": "2026-07-25T00:46:45Z",
  "tool": "imessage_send_message",
  "target": "Sarah (+14802016076)",
  "dry_run": true,
  "status": "success",
  "duration_ms": 42
}

Known Limitations & Considerations

1. Host Mac Requirement: Must run on a physical Mac or macOS VM signed into an active Apple ID.

2. AppleScript Attachment Sandboxing: Native AppleScript send alias in macOS Sonoma/Sequoia marks attachments as "Not Delivered". This server bypasses that bug using a Swift NSPasteboard paste workflow; therefore, the host Mac must be in an active Aqua GUI session.

3. Read-Only SQLite Access: Database reads use URI mode=ro (sqlite3.connect('file:chat.db?mode=ro', uri=True)) to ensure chat.db is never locked or corrupted by server reads.

4. SMS vs iMessage: Text-only messages fallback gracefully to SMS if the recipient handle is a mobile phone number registered on your iPhone's Text Message Forwarding network.

License

This project is licensed under the MIT License.