imessage-mcp
imessage-mcp
一个将 Mac 的 iMessage 数据暴露给 Claude Desktop / Claude Code 的本地 MCP 服务器。 包含两个功能面:
发送:通过 AppleScript →
Messages.app读取:通过直接、只读的 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。)
工具
工具 | 用途 |
| 通过 Messages.app 发送。 |
| 按最新顺序排列的聊天列表,包含最后一条消息预览和未读计数。 |
| 获取聊天记录;提供 |
| 在消息正文中进行不区分大小写的 LIKE 查询。 |
| 获取个人句柄(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 -qAvailable Tools
6 toolsget_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
Scored across 6 tools
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.
All tool names follow a consistent verb_noun pattern (get_, list_, resolve_, search_, send_), making the API predictable and easy to navigate.
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.
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
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables full-text search of macOS iMessages including link preview metadata. Works as an MCP server for Claude Desktop to search your messages locally.1MIT
- FlicenseAqualityDmaintenanceA read-only MCP server that exposes your iMessage data to Claude Code and Claude Desktop, with automatic contact name resolution.3-
- AlicenseAqualityDmaintenanceA 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.3MIT
- AlicenseAqualityCmaintenanceLocal MCP server for reading macOS Messages history and sending iMessages, with security features like opt-in send tools and recipient allowlists.4MIT