claude-imessage-mcp

Claude iMessage MCP Server

🦞 一个用于 Claude Code 的 MCP (Model Context Protocol) 服务器，让 Claude 可以通过 iMessage 发送和接收消息。

特性

• 📤 发送消息: 通过 Claude Code 发送 iMessage/SMS 消息
• 📥 接收消息: 实时监听新消息
• 📋 聊天列表: 查看最近的聊天记录
• 🔍 历史记录: 获取聊天历史消息
• 📎 附件支持: 发送图片、文件等附件
• 🔄 实时监听: 持续监听新消息（watch 模式）

系统要求

• 操作系统: macOS (iMessage 仅支持 macOS)
• Node.js: >= 18.0.0
• imsg CLI: 需要安装 imsg
• 系统权限:
• 完全磁盘访问权限（读取 Messages 数据库）
• 自动化权限（控制 Messages.app）

快速开始

1. 安装 imsg

brew install steipete/tap/imsg

2. 克隆并安装项目

git clone https://github.com/yourusername/claude-imessage-mcp.git
cd claude-imessage-mcp
npm install

3. 配置系统权限

前往 系统设置 → 隐私与安全:

1. 完全磁盘访问: 添加你的终端应用（Terminal.app 或 iTerm.app）
2. 自动化: 允许终端控制 Messages.app

4. 测试安装

npm test

5. 配置 Claude Code

编辑 Claude Code 配置文件（~/.claude/config.json）:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/绝对路径/claude-imessage-mcp/index.js"]
    }
  }
}

或者使用 npx:

{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "claude-imessage-mcp"]
    }
  }
}

6. 重启 Claude Code

claude restart

使用方法

在 Claude Code 中，你可以使用以下命令与 iMessage 交互:

发送消息

给 +86xxxxxxxxxx 发送一条消息："你好！"

Claude 会调用 send_imessage 工具发送消息。

查看聊天列表

显示我最近的 iMessage 聊天

获取聊天历史

获取 chat_id 123 的历史消息

实时监听消息

开始监听新的 iMessage 消息

这会启动实时监听模式，新消息会在 Claude Code 的输出中显示。

停止监听

停止监听 iMessage

可用工具

send_imessage

发送 iMessage 消息。

参数:

• to (必需): 收件人电话号码或邮箱
• text (必需): 消息内容
• file (可选): 附件文件路径

示例: ``json { "to": "+86xxxxxxxxxx", "text": "Hello from Claude!", "file": "/path/to/image.jpg" } ``

list_imessage_chats

列出最近的聊天。

参数:

• limit (可选): 返回数量，默认 20

get_imessage_history

获取聊天历史。

参数:

• chat_id (必需): 聊天 ID
• limit (可选): 消息数量，默认 50
• attachments (可选): 是否包含附件信息，默认 false

watch_imessage

开始监听新消息。

参数:

• chat_id (可选): 仅监听特定聊天

stop_watch_imessage

停止监听消息。

架构说明

本项目基于 OpenClaw 的 iMessage 集成方案，使用以下技术架构:

iMessage (Messages.app)
  ↓
chat.db (SQLite 数据库)
  ↓
imsg CLI (Swift 工具)
  ↓
MCP Server (本项目)
  ↓
Claude Code

核心组件

1. imsg: Swift 编写的 CLI 工具，通过 AppleScript 发送消息，通过读取 chat.db 接收消息
2. MCP Server: 提供标准化的工具接口给 Claude Code
3. ImsgWatcher: 实时监听消息的 EventEmitter

开发

运行开发模式

npm run dev

使用 nodemon 自动重启服务器。

调试

MCP Server 的日志输出到 stderr，可以在 Claude Code 的日志中查看:

tail -f ~/.claude/logs/mcp-imessage.log

贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

常见问题

Q: 提示 "imsg not found"

A: 安装 imsg: brew install steipete/tap/imsg

Q: 发送消息失败

A: 检查以下几点:

1. 终端是否有自动化权限
2. Messages.app 是否已登录
3. 电话号码格式是否正确（建议使用 E.164 格式，如 +86xxxxxxxxxx）

Q: 无法读取消息

A: 终端需要完全磁盘访问权限才能读取 ~/Library/Messages/chat.db

Q: 实时监听不工作

A:

1. 确认 imsg watch 命令可以正常运行
2. 检查 Messages.app 是否在运行
3. 尝试手动发送一条测试消息

Q: 如何发送 SMS（非 iMessage）？

A:

1. 确保 iPhone 上启用了"短信转发"
2. Mac 和 iPhone 在同一 Apple ID 下登录
3. 使用电话号码发送即可自动通过 SMS

相关项目

• imsg - iMessage CLI 工具
• OpenClaw - 个人 AI 助手框架
• MCP SDK - Model Context Protocol SDK

安全性说明

• 本项目不会上传任何消息内容到远程服务器
• 所有数据处理均在本地完成
• Messages 数据库以只读模式访问
• 建议仅在可信设备上使用

许可证

MIT License - 详见 LICENSE 文件

致谢

• Peter Steinberger - imsg 工具的作者
• OpenClaw - 提供了 iMessage 集成的灵感
• Anthropic - Claude 和 MCP 协议

---

Made with 🦞 for Claude Code