Skip to main content
Glama
joshkaplan-dev

Imessage-MCP

by joshkaplan-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Read-only iMessage MCP server

Gives an assistant read-only access to your macOS Messages so it can help you read, search, and analyze texts. It cannot send, edit, or delete anything — every database connection is opened with SQLite mode=ro. You send replies yourself.

What it reads

  • ~/Library/Messages/chat.db — your iMessage/SMS history (read-only)

  • ~/Library/Application Support/AddressBook/.../AddressBook-v22.abcddb — to turn phone numbers/emails into contact names (read-only, best effort)

It never writes to, copies, or transmits these anywhere — it just answers queries from whichever Claude client is connected.

Related MCP server: imessage-mcp

Tools

Tool

What it does

list_conversations

Most recently active threads + last-message preview

list_unreplied

Threads where the other person texted last (awaiting your reply)

get_conversation

Recent message history with a person or group (fuzzy name/phone/email match)

search_messages

Full-text search across messages, optionally scoped to one contact

get_recent_messages

Inbox-style view of recent messages across all threads (optional hours window)

Requirements

  • uv installed (handles the Python deps automatically).

  • Full Disk Access for whatever app runs the server, because chat.db is protected:

    • Claude Code (CLI): the terminal app you launch claude from (Terminal, iTerm, etc.).

    • Claude Desktop: the Claude.app itself. Grant it in System Settings → Privacy & Security → Full Disk Access, then restart the app.

How it's wired up

  • Claude Code: registered at user scope (~/.claude.json). Remove with claude mcp remove imessage-readonly.

  • Claude Desktop: added under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (a timestamped .bak of the original sits next to it). Restart the app to load it.

Notes

  • On recent macOS the message text is stored in a binary attributedBody blob rather than the text column; server.py decodes it (handles emoji/accents).

  • Timestamps are converted from Apple absolute time (nanoseconds since 2001-01-01).

  • Override the database path with the IMESSAGE_DB environment variable if needed.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • iMessage MCP Server

    sameelarif
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables reading, searching, and sending iMessages directly from MCP-compatible clients by accessing the local macOS iMessage database, supporting conversations, attachments, and both individual and group chats.
    246 npm
    10
    MIT

  • multimodal-imessage-mcp

    tszaks
    A
    license
    B
    quality
    B
    maintenance
    Enables reading, searching, sending iMessages, viewing image attachments, and managing conversations, with full support for modern macOS attributedBody parsing.
    14
    1
    MIT