Skip to main content
Glama

imessage-mcp

一个将 Mac 的 iMessage 数据暴露给 Claude Desktop / Claude Code 的本地 MCP 服务器。 包含两个功能面:

  1. 发送:通过 AppleScript → Messages.app

  2. 读取:通过直接、只读的 SQLite 访问 ~/Library/Messages/chat.db

一切都在本地运行。无需 API 密钥,无网络调用。

安装

# 1. Clone / copy into ~/mcp-servers/imessage-mcp
cd ~/mcp-servers/imessage-mcp

# 2. Create a Python 3.11+ venv and install deps
python3.12 -m venv .venv
.venv/bin/pip install -e .

Related MCP server: imessage-mcp

权限(必需)

完全磁盘访问权限 — 以便读取 chat.db

系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 为以下应用开启开关:

  • 您的终端应用(例如 Terminal, iTerm2, Ghostty),以及

  • Claude.app(如果使用 Claude Desktop)

自动化 — 以便控制 Messages.app

系统设置 → 隐私与安全性 → 自动化 → 展开您的终端 / Claude.app 并将 Messages 开关打开。

Messages.app 必须处于运行状态并已登录 iMessage。

如果缺少权限步骤,服务器会报错并给出需要打开的具体设置路径。

Claude Desktop 配置

合并到 ~/Library/Application Support/Claude/claude_desktop_config.json 中:

{
  "mcpServers": {
    "imessage": {
      "command": "/Users/YOUR_USERNAME/mcp-servers/imessage-mcp/.venv/bin/python",
      "args": ["-m", "imessage_mcp.server"]
    }
  }
}

(使用 venv 中 python 的绝对路径是最安全的 — 它可以避免 PATH 歧义。请替换 YOUR_USERNAME。)

工具

工具

用途

send_imessage(recipient, body, service?)

通过 Messages.app 发送。recipient 是电话号码、Apple ID 邮箱或现有的好友名称。

list_recent_chats(limit=20)

按最新顺序排列的聊天列表,包含最后一条消息预览和未读计数。

get_chat_messages(chat_id?, handle?, limit=50, since?)

获取聊天记录;提供 chat_id 或 handle。

search_imessages(query, since?, until?, from_contact?, limit=25)

在消息正文中进行不区分大小写的 LIKE 查询。

get_my_info()

获取个人句柄(handle)+ 数据库元数据。

日期格式为 ISO8601。在内部,Apple 将 message.date 存储为自 2001-01-01 UTC 以来的纳秒数;服务器会进行双向转换。

安全不变性

  • chat.db 以 sqlite3.connect("file:...chat.db?mode=ro", uri=True) 方式打开。 任何写入尝试都会引发 sqlite3.OperationalError: attempt to write a readonly database。

  • send_imessage 将接收者 / 正文 / 服务作为 独立的 osascript 参数 传递 ——无 shell 插值,无注入风险。

  • 附件仅返回元数据(文件名、mime_type、总字节数)。从不读取二进制数据(Blob)。

限制

  • 不支持定时 / 延迟发送。

  • 富文本 / 回复线程消息的文本可能存储在 attributedBody (NSKeyedArchive) 中。 我们尽力提取嵌入的 NSString;具有更复杂负载(图片、点按反馈、Apple Pay)的消息将显示为空 body,但元数据正确。

  • 送达确认:send_imessage 根据 osascript 的退出代码报告成功。要验证消息是否确实发送成功,请在几秒钟后调用 search_imessages 或 get_chat_messages。

  • 此工具仅限 macOS 使用,在沙盒化的 App Store 应用中无法工作。

本地开发

.venv/bin/pytest -q

Available Tools

6 tools
get_chat_messagesA

Return messages for a chat. Provide chat_id or handle (phone/email).

since is an ISO8601 datetime. Attachments are metadata only.

Inputs: chat_id, handle, limit, since. Returns: result

get_my_infoA

Return self-handles and chat.db metadata for sanity checks.

Inputs: no named parameters. Returns: object

list_recent_chatsB

List recent chats, newest-first, with previews and unread counts.

Inputs: limit. Returns: result

resolve_contactA

Resolve an iMessage handle to a name, or a name to handles.

Provide either handle (phone like +15551234567 or email) or name. Checks a local JSON cache first, then falls back to the macOS AddressBook SQLite. New hits are written back to the cache for future sessions.

Inputs: name, handle. Returns: object

search_imessagesA

Case-insensitive LIKE search over message bodies. Dates are ISO8601.

Inputs: query (required), since, until, from_contact, +1 more. Returns: result

send_imessageA

Send an iMessage/SMS via Messages.app.

Args: recipient: phone (+15551234567), Apple ID email, or an existing buddy name. body: message text. service: "iMessage" (default) or "SMS".

Inputs: recipient (required), body (required), service. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: retrieving messages by chat or search, listing chats, resolving contacts, sending messages, and getting self info. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_, list_, resolve_, search_, send_), making the API predictable and easy to navigate.

    Tool Count5/5

    With 6 tools covering core iMessage operations (read, send, search, list, resolve), the set is well-scoped and each tool earns its place without unnecessary bloat.

    Completeness4/5

    Covers essential CRUD-like operations (read via chat or search, send, list) plus contact resolution and self-info. Missing message deletion or editing, but those are uncommon for MCP servers, so no significant gap.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables full-text search of macOS iMessages including link preview metadata. Works as an MCP server for Claude Desktop to search your messages locally.
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that exposes your iMessage data to Claude Code and Claude Desktop, with automatic contact name resolution.
      3
      -
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that lets Claude Desktop interact with Apple Mail on macOS via AppleScript. It enables listing mailboxes, searching emails, and reading email content without making network calls.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local MCP server for reading macOS Messages history and sending iMessages, with security features like opt-in send tools and recipient allowlists.
      4
      MIT