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。）

工具

日期格式为 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