iMessage MCP

一个本地 MCP 服务器，可读取你的 macOS 信息历史记录并发送新的 iMessage。一切都在本地运行——没有任何数据离开你的设备。

工具

读取工具每次调用最多返回 200 行，且不包含轻点回应（tapbacks）。除非设置了 IMESSAGE_MCP_ALLOW_SEND=1，否则这两个发送工具根本不会注册，因此配置为只读的主机即使误操作也无法发送。

Related MCP server: imessage-mcp

安全模型

读取你的消息和以你的身份发送消息是两种截然不同的权限，而将两者放在同一个代理会话中才是风险所在。任何能给你发短信的人都可以向 get_recent_messages 注入文本，因此消息正文是攻击者可控的输入，而它旁边就放着一个以你的身份发送消息的工具。

此服务器对此采取的措施：

• 发送工具默认关闭，必须按主机单独开启。

• IMESSAGE_MCP_ALLOWED_RECIPIENTS 限制可以联系的对象。

• 每次发送尝试及结果都会在 AppleScript 调用前后追加到本地审计日志中，因此任何发送都会留下记录。

• 外发消息有长度上限，且不能为空。

• 服务器会公布 MCP instructions 和每个工具的注解（readOnlyHint、destructiveHint），以便主机对危险工具进行提示。

它不能做到的是：无法阻止模型在读取恶意消息后决定对其采取行动。如果你启用了发送功能，请务必在发送工具上保留审批提示。

配置

全部为可选配置。请在 MCP 主机的配置文件中设置，而不是在 shell 配置文件中。

设置

git clone https://github.com/tarun101/imessage-mcp.git
cd imessage-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

需要 Python 3.10 或更高版本。以下所有内容均假设 $REPO 是你克隆仓库的绝对路径。

mcp 依赖被固定为 <2。2.x SDK 移除了此服务器所导入的 mcp.server.fastmcp；未固定版本的安装会获取 2.x 并在启动时失败。

macOS 权限（两者都需要）

1. 完全磁盘访问权限 — 没有此权限将无法读取 ~/Library/Messages/chat.db。请将运行服务器的进程（Terminal、iTerm 或你的 MCP 主机应用）添加到系统设置 → 隐私与安全性 → 完全磁盘访问权限中，然后完全退出并重新打开。

2. 自动化 → 信息 — 首次调用 send_message/send_to_chat 时会触发一次控制 Messages.app 的权限提示。请允许。

快速测试

source .venv/bin/activate
python -c "import server; print(server.list_chats(5))"

测试

pip install -e '.[dev]'
pytest

测试套件会使用 Apple 的 schema 构建一个合成的 chat.db，因此可以在任何地方运行——无需 Mac，也无需访问你的真实消息历史。

注册到 MCP 主机

Codex

codex mcp add imessage --env IMESSAGE_MCP_ALLOW_SEND=1 -- \
  "$REPO/.venv/bin/python" "$REPO/server.py"

或者在 ~/.codex/config.toml 中配置，这还可以让你按工具要求审批：

[mcp_servers.imessage]
command = "/absolute/path/to/imessage-mcp/.venv/bin/python"
args = ["/absolute/path/to/imessage-mcp/server.py"]
default_tools_approval_mode = "auto"

[mcp_servers.imessage.env]
IMESSAGE_MCP_ALLOW_SEND = "1"

[mcp_servers.imessage.tools.send_message]
approval_mode = "prompt"

[mcp_servers.imessage.tools.send_to_chat]
approval_mode = "prompt"

在 Codex TUI 中使用 /mcp 验证。

Claude Code (CLI)

claude mcp add imessage -- "$REPO/.venv/bin/python" "$REPO/server.py"

Claude Desktop / 通用 MCP 配置

{
  "mcpServers": {
    "imessage": {
      "command": "/absolute/path/to/imessage-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/imessage-mcp/server.py"]
    }
  }
}

使用绝对路径，以确保使用 venv 中的 Python（已安装 mcp）。

注意事项与限制

• 只读数据库访问。 chat.db 以 mode=ro 打开；服务器绝不会写入你的消息存储。发送完全通过 Messages.app 进行。

• WAL 回退。 chat.db 是一个 WAL 数据库，只读句柄无法创建其所需的 -shm 文件。当直接打开失败时（例如 Messages.app 未运行），服务器会透明地读取临时快照副本，并在源文件变化时刷新。

• attributedBody。 较新的消息将正文存储在二进制 attributedBody 数据块中，而不是 text 列。读取器会以启发式方式解码这些数据——可以覆盖普通文本消息，但可能遗漏富内容。因此，search_messages 只匹配纯 text 列。

• 时间戳以 ISO-8601 UTC 格式返回。

• 发送结果会被验证，而非假设。 AppleScript 在投递前就会返回，因此发送后服务器会轮询 chat.db 查找外发记录。结果为 sent_unverified 表示 Messages.app 已接受但尚未送达——通常是延迟而非失败。

• 发送是真实操作。 这些工具会发送真实的消息，且无法撤回。