Mac Messages Host

你的 Mac 上完整的 Apple Messages（iMessage/SMS）历史记录，只读，供 AI 代理使用 —— 一个通过 REST/OpenAPI 和可流式 HTTP MCP 提供的批处理工具。

• 一个工具，批量请求：单个 messages(requests: str) 工具接收一个 JSON 请求数组，并返回一个对齐的 JSON 响应数组——一次调用完成许多独立的操作。它通过 REST（POST /api/messages）和 MCP（/mcp/）提供完全相同的功能。

• 构造上只读：数据库以 SQLite mode=ro 方式打开；没有任何写入路径。无法发送、编辑或删除任何内容。

• 现代 macOS 正文解码：存储在 attributedBody typedstream 块（Ventura 及更高版本）中的消息文本，以及 message_summary_info plist 中的编辑历史，都会被透明地解码。

• 自动生成的工具提示词：面向 AI 的提示词由 Pydantic 模型生成（约 615 个 gpt-4o token，由 tiktoken 计数并由测试强制约束）；tool_prompt.md 快照通过漂移测试保持同步。

安装

需要 macOS 上的 Python 3.11+。

pip install .            # or: pip install -e . for development
mmhost info              # permission check + database status
mmhost start             # serve API + MCP on http://127.0.0.1:8761

macOS 权限（重要）

~/Library/Messages/chat.db 受 macOS TCC 保护。运行 mmhost 的进程需要具有完全磁盘访问权限：

System Settings → Privacy & Security → Full Disk Access → 启用你的终端应用（或任何启动服务器的程序），然后重新启动它。

mmhost info 会立即告诉你数据库是否可读。

Related MCP server: jons-mcp-imessage

端点

认证

当配置了 admin_token（持久化配置、MMHOST_ADMIN_TOKEN 或 --admin-token）时，使用 Authorization: Bearer <token>。如果未配置令牌，则访问是开放的——这是安全的，因为服务器默认绑定 127.0.0.1。

请求类型

• get_info — 数据库状态、计数、历史日期范围

• list_chats — 按最近活跃度列出会话（筛选、分页）

• get_chat — 某个会话的完整记录（通过 before 向前分页）

• get_recent — 所有会话中的最新消息（通过 since 轮询）

• search_messages — 对正文进行不区分大小写的子串搜索

有关由模型生成的准确面向 AI 的文档，请参阅 tool_prompt.md。

示例

curl -s http://127.0.0.1:8761/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"requests": "[{\"kind\":\"list_chats\",\"limit\":3}]"}'

MCP 客户端配置

{
  "mcpServers": {
    "mac-messages": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8761/mcp/"
    }
  }
}

配置

持久化保存在平台配置目录中（macOS 上为 ~/Library/Application Support/mac_messages_host/config.json）；可以通过 MMHOST_CONFIG 覆盖位置。仅包含服务器级设置——参阅 example.env。

开发

pip install -e '.[dev]'
pytest
# after changing request models:
python -m tests.regenerate_tool_prompt

架构遵循 oWoHo AI Tool Server 模式（纯核心库 + 派生的 FastAPI/FastMCP/CLI 接口），与 reddit_tool_server 和 obsidian_ai_miniserver 类似。

许可证

MIT——参阅 LICENSE.md。