imessage-mcp-server 1.0.0 → 2.0.0

package/README.md

@@ -1,7 +1,9 @@
 # imessage-mcp-server
 
-> **MCP server for reading and sending iMessages on macOS**  
-> Expose your iMessage history and send capabilities via the [Model Context Protocol](https://modelcontextprotocol.io).
+> **MCP server + AI bridge for iMessage on macOS**  
+> Expose your iMessage history and send capabilities via the [Model Context Protocol](https://modelcontextprotocol.io), or turn your Mac into a 24/7 AI assistant that auto-replies to your iMessages.
+
+[中文 README](README.zh.md)
 
 ⚠️ **macOS only** — requires the Messages app and its SQLite database (`~/Library/Messages/chat.db`).
 
@@ -9,15 +11,26 @@
 
 ## Features
 
-This MCP server provides **4 tools** for interacting with iMessage:
+### MCP Server mode
+Four standard MCP tools for reading and sending iMessages:
 
 | Tool | Description |
 |------|-------------|
 | `send_imessage` | Send an iMessage to a recipient's email or phone number |
 | `list_conversations` | List recent conversations with latest message preview and unread count |
-| `read_conversation` | Read paginated messages from a specific conversation (by chat_id or handle) |
+| `read_conversation` | Read paginated messages from a specific conversation |
 | `get_new_messages` | Poll for new incoming messages since a timestamp |
 
+### Bridge mode
+Run an autonomous AI agent in the background:
+
+- Polls for new iMessages from your configured `masterHandle`
+- Sends them to Claude, OpenAI, DeepSeek, Kimi, or any OpenAI-compatible model
+- Connects any MCP Servers as tools (filesystem, shell, git, etc.)
+- Auto-replies with results
+- Remembers conversation context
+- Supports macOS LaunchAgent for auto-start on login
+
 ---
 
 ## Prerequisites
@@ -38,31 +51,31 @@ xcode-select --install
 
 ## Quick Start
 
-### Option 1: npx (recommended)
+### MCP Server mode
 
-No installation needed — just add to your MCP configuration:
+Add to your MCP configuration:
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+**Claude Code** (`.claude/settings.json`):
 
 ```json
 {
   "mcpServers": {
     "imessage": {
       "command": "npx",
-      "args": ["-y", "imessage-mcp-server"]
+      "args": ["-y", "imessage-mcp-server", "--server"]
     }
   }
 }
 ```
 
-**Claude Code** (`.claude/settings.json` in your project):
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "imessage": {
       "command": "npx",
-      "args": ["-y", "imessage-mcp-server"]
+      "args": ["-y", "imessage-mcp-server", "--server"]
     }
   }
 }
@@ -75,7 +88,7 @@ No installation needed — just add to your MCP configuration:
   "mcpServers": {
     "imessage": {
       "command": "npx",
-      "args": ["-y", "imessage-mcp-server"]
+      "args": ["-y", "imessage-mcp-server", "--server"]
     }
   }
 }
@@ -88,138 +101,205 @@ No installation needed — just add to your MCP configuration:
   "servers": {
     "imessage": {
       "command": "npx",
-      "args": ["-y", "imessage-mcp-server"]
+      "args": ["-y", "imessage-mcp-server", "--server"]
     }
   }
 }
 ```
 
-### Option 2: Global install
-
-```bash
-npm install -g imessage-mcp-server
-```
+### Bridge mode
 
-Then reference the binary directly in your MCP config:
+Create a `bridge-config.json`:
 
 ```json
 {
+  "masterHandle": "your-email@icloud.com",
+  "provider": "anthropic",
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "model": "claude-3-5-sonnet-20241022",
   "mcpServers": {
-    "imessage": {
-      "command": "imessage-mcp",
-      "args": []
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/YOU"]
     }
   }
 }
 ```
 
-### Option 3: Clone from source
+Run in foreground for testing:
 
 ```bash
-git clone https://github.com/tinyxia/imessage-mcp.git
-cd imessage-mcp
-npm install
+npx imessage-mcp-server --bridge --config ./bridge-config.json --foreground
 ```
 
-Then reference the local path:
+Install as a macOS LaunchAgent (auto-start on login):
+
+```bash
+npx imessage-mcp-server --bridge --install-service --config ./bridge-config.json
+npx imessage-mcp-server --bridge --status
+npx imessage-mcp-server --bridge --uninstall
+```
+
+> **Note:** When running as a LaunchAgent, the bridge does **not** inherit environment variables from your shell. If your `apiKey` uses `${ANTHROPIC_API_KEY}` env substitution, the service won't be able to resolve it. Put the API key directly in the config file instead.
+
+---
+
+## CLI Reference
+
+```bash
+# Show help / version
+npx imessage-mcp-server --help
+npx imessage-mcp-server --version
+
+# MCP Server mode
+npx imessage-mcp-server --server
+
+# Bridge mode
+npx imessage-mcp-server --bridge --config ./bridge-config.json
+npx imessage-mcp-server --bridge --foreground
+npx imessage-mcp-server --bridge --test-config
+npx imessage-mcp-server --bridge --install-service --config ./bridge-config.json
+npx imessage-mcp-server --bridge --status
+npx imessage-mcp-server --bridge --uninstall
+```
+
+---
+
+## Bridge Configuration
+
+### Full schema
 
 ```json
 {
+  "masterHandle": "your-email@icloud.com",
+  "provider": "anthropic",
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "baseUrl": null,
+  "model": "claude-3-5-sonnet-20241022",
+  "maxTokens": 4096,
+  "pollIntervalMs": 3000,
+  "maxHistoryPerConversation": 20,
+  "maxToolIterations": 10,
+  "sendProcessingIndicator": true,
+  "systemPrompt": "Optional custom system prompt",
+  "projectDir": "/Users/YOU/project",
   "mcpServers": {
-    "imessage": {
-      "command": "node",
-      "args": ["/path/to/imessage-mcp/index.js"]
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/YOU"]
+    },
+    "shell": {
+      "command": "npx",
+      "args": ["-y", "mcp-shell-server"]
     }
+  },
+  "safety": {
+    "requireConfirmation": false,
+    "allowedTools": null,
+    "blockedTools": [],
+    "blockedCommands": ["rm -rf /", "sudo"],
+    "readOnly": false
   }
 }
 ```
 
+### Supported providers
+
+| Provider | `provider` value | Notes |
+|----------|------------------|-------|
+| Anthropic / Claude | `anthropic` or `claude` | Native thinking blocks |
+| OpenAI | `openai` | Official API |
+| DeepSeek | `deepseek` | OpenAI-compatible endpoint |
+| Kimi | `kimi` | OpenAI-compatible endpoint |
+| Any OpenAI-compatible | `openai` | Set `baseUrl` |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `IMESSAGE_DB_PATH` | Override the path to `chat.db` |
+| `IMESSAGE_MASTER_HANDLE` | Your iMessage handle for bridge mode |
+| `IMESSAGE_PROVIDER` | Default LLM provider |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | API keys |
+| `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` | Custom API endpoints |
+
+Config files support `${VAR_NAME}` syntax for env substitution.
+
 ---
 
-## Tool Reference
+## MCP Tools (Server mode)
 
 ### `send_imessage`
 
 Send an iMessage to a recipient.
 
-**Parameters:**
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `recipient` | string | ✅ | Email address or phone number of the recipient |
-| `text` | string | ✅ | Message text to send |
-
-**Example:**
 ```json
 { "recipient": "example@icloud.com", "text": "Hello from MCP!" }
 ```
 
 ### `list_conversations`
 
-List recent conversations with the latest message preview and unread count.
-
-**Parameters:**
+List recent iMessage conversations.
 
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `limit` | number | ❌ | 20 | Max conversations to return (max 100) |
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `limit` | number | 20 | Max conversations (max 100) |
 
 ### `read_conversation`
 
 Read messages from a specific conversation.
 
-**Parameters:**
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `handle` | string | ❌ | — | Filter by handle (email or phone number) |
-| `chat_id` | number | ❌ | — | Filter by chat ROWID |
-| `limit` | number | ❌ | 30 | Max messages to return (max 200) |
-| `before_id` | number | ❌ | — | Paginate: return messages before this ROWID |
-| `include_read` | boolean | ❌ | true | Include already-read messages |
-| `unread_only` | boolean | ❌ | false | Only return unread messages |
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `handle` | string | — | Filter by email/phone |
+| `chat_id` | number | — | Filter by chat ROWID |
+| `limit` | number | 30 | Max messages (max 200) |
+| `before_id` | number | — | Paginate before ROWID |
+| `include_read` | boolean | true | Include read messages |
+| `unread_only` | boolean | false | Only unread |
 
 ### `get_new_messages`
 
 Poll for recently received messages.
 
-**Parameters:**
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `since` | string | ❌ | last 10 | ISO timestamp to fetch messages from (e.g. `2026-06-28T10:00:00.000Z`) |
-| `mark_read` | boolean | ❌ | false | Mark unread messages as read in chat.db |
-| `max_results` | number | ❌ | 10 | Max messages to return (max 100) |
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `since` | string | — | ISO timestamp |
+| `max_results` | number | 10 | Max messages (max 100) |
+| `unread_only` | boolean | false | Only unread |
 
 ---
 
-## Environment Variables
+## Bridge Tools
+
+In bridge mode, the AI can use any tools exposed by the configured MCP servers, plus two built-in local tools:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `IMESSAGE_DB_PATH` | `~/Library/Messages/chat.db` | Override the path to the iMessage chat database |
+- `send_imessage` — send a message to any recipient
+- `send_long_reply` — split a long response into multiple iMessages
 
 ---
 
-## Troubleshooting
+## Security Notes
 
-| Problem | Solution |
-|---------|----------|
-| ❌ **iMessage database not found** | Make sure you are signed into iMessage in the Messages app. If your database is in a non-standard location, set `IMESSAGE_DB_PATH`. |
-| 🔒 **Permission denied / database unreadable** | Grant **Full Disk Access** to your terminal/IDE in _System Settings → Privacy & Security → Full Disk Access_. Restart your terminal after granting. |
-| 🔐 **"Database is locked"** | Quit the Messages app completely or wait for sync to finish. |
-| 💻 **osascript failed** | Make sure Messages.app is running and signed into your Apple ID. |
-| ⚠️ **better-sqlite3 compilation errors** | Install Xcode CLI Tools: `xcode-select --install` and try again. |
-| 🐢 **First `npx` run is slow** | npx downloads and compiles native modules on first run. Subsequent runs are cached. |
+- The iMessage database is opened in **read-only mode** for all read operations.
+- Bridge mode only processes messages from the configured `masterHandle`; all other senders are ignored.
+- Use `safety.readOnly: true` to prevent write tools.
+- Use `safety.allowedTools` to whitelist allowed tools.
+- Use `safety.blockedCommands` to blacklist dangerous shell patterns.
+- All chat data stays on your Mac; only API calls to your chosen LLM provider leave the machine.
 
 ---
 
-## Security Notes
+## Troubleshooting
 
-- The iMessage database is opened in **read-only mode** (`chat.db` is never modified by read operations)
-- The `mark_read` option in `get_new_messages` is the only operation that writes to the database
-- Sending messages is done through **AppleScript** (`osascript`) which respects macOS privacy controls
-- Your chat data **never leaves your machine** — all processing is local
+| Problem | Solution |
+|---------|----------|
+| ❌ iMessage database not found | Sign into Messages app or set `IMESSAGE_DB_PATH`. |
+| 🔒 Permission denied | Grant **Full Disk Access** to your terminal/IDE. |
+| 🔐 "Database is locked" | Quit Messages app or wait for sync. |
+| 💻 osascript failed | Make sure Messages.app is running and signed in. |
+| ⚠️ better-sqlite3 compile errors | Run `xcode-select --install`. |
+| 🐢 First `npx` run is slow | Native modules compile on first run; later runs are cached. |
 
 ---
 

package/README.zh.md

@@ -0,0 +1,310 @@
+# imessage-mcp-server
+
+> **macOS 上的 iMessage MCP Server + AI Bridge**  
+> 通过 [Model Context Protocol](https://modelcontextprotocol.io) 暴露你的 iMessage 读写能力，或者把你的 Mac 变成 24 小时在线的 iMessage AI 助手。
+
+[English README](README.md)
+
+⚠️ **仅限 macOS** — 需要系统「信息」应用及其 SQLite 数据库（`~/Library/Messages/chat.db`）。
+
+---
+
+## 功能特性
+
+### MCP Server 模式
+
+提供 4 个标准 MCP 工具，用于读取和发送 iMessage：
+
+| 工具 | 说明 |
+| ------ | ------ |
+| `send_imessage` | 向指定邮箱或手机号发送 iMessage |
+| `list_conversations` | 列出最近会话，含最新消息摘要和未读数 |
+| `read_conversation` | 读取某个会话的分页消息 |
+| `get_new_messages` | 按时间戳轮询新收到的消息 |
+
+### Bridge 模式
+
+在后台运行一个自主 AI Agent：
+
+- 轮询你指定的 `masterHandle` 发来的新 iMessage
+- 调用 Claude、OpenAI、DeepSeek、Kimi 或任意 OpenAI 兼容模型
+- 连接任意 MCP Server 作为工具（文件系统、Shell、Git 等）
+- 自动把结果通过 iMessage 回复给你
+- 记住多轮对话上下文
+- 支持 macOS LaunchAgent 开机自启
+
+---
+
+## 环境要求
+
+- **macOS**（建议 Ventura 或更新版本）
+- **Node.js >= 18**
+- 已在「信息」App 中**登录 iMessage**
+- 给终端 / IDE 授予**完全磁盘访问权限**
+  - 系统设置 → 隐私与安全性 → 完全磁盘访问权限
+  - 添加你的终端应用（Terminal、iTerm2、VS Code 等）
+- **Xcode 命令行工具**（用于编译原生模块 `better-sqlite3`）
+
+```bash
+xcode-select --install
+```
+
+---
+
+## 快速开始
+
+### MCP Server 模式
+
+把以下内容加到 MCP 客户端配置中：
+
+**Claude Code**（`.claude/settings.json`）：
+
+```json
+{
+  "mcpServers": {
+    "imessage": {
+      "command": "npx",
+      "args": ["-y", "imessage-mcp-server", "--server"]
+    }
+  }
+}
+```
+
+**Claude Desktop**（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "imessage": {
+      "command": "npx",
+      "args": ["-y", "imessage-mcp-server", "--server"]
+    }
+  }
+}
+```
+
+**Cursor**（`.cursor/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "imessage": {
+      "command": "npx",
+      "args": ["-y", "imessage-mcp-server", "--server"]
+    }
+  }
+}
+```
+
+**VS Code + GitHub Copilot**（`.vscode/mcp.json`）：
+
+```json
+{
+  "servers": {
+    "imessage": {
+      "command": "npx",
+      "args": ["-y", "imessage-mcp-server", "--server"]
+    }
+  }
+}
+```
+
+### Bridge 模式
+
+创建 `bridge-config.json`：
+
+```json
+{
+  "masterHandle": "你的邮箱@icloud.com",
+  "provider": "anthropic",
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "model": "claude-3-5-sonnet-20241022",
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名"]
+    }
+  }
+}
+```
+
+前台测试运行：
+
+```bash
+npx imessage-mcp-server --bridge --config ./bridge-config.json --foreground
+```
+
+安装为 macOS LaunchAgent（开机自启）：
+
+```bash
+npx imessage-mcp-server --bridge --install-service --config ./bridge-config.json
+npx imessage-mcp-server --bridge --status
+npx imessage-mcp-server --bridge --uninstall
+```
+
+> **注意**：LaunchAgent 不会继承 shell 的环境变量。如果 `apiKey` 使用 `${ANTHROPIC_API_KEY}` 这种环境变量引用，服务启动时会读不到。建议直接把 API Key 写入配置文件。
+
+---
+
+## CLI 参考
+
+```bash
+# 查看帮助 / 版本
+npx imessage-mcp-server --help
+npx imessage-mcp-server --version
+
+# MCP Server 模式
+npx imessage-mcp-server --server
+
+# Bridge 模式
+npx imessage-mcp-server --bridge --config ./bridge-config.json
+npx imessage-mcp-server --bridge --foreground
+npx imessage-mcp-server --bridge --test-config
+npx imessage-mcp-server --bridge --install-service --config ./bridge-config.json
+npx imessage-mcp-server --bridge --status
+npx imessage-mcp-server --bridge --uninstall
+```
+
+---
+
+## Bridge 配置说明
+
+### 完整配置示例
+
+```json
+{
+  "masterHandle": "你的邮箱@icloud.com",
+  "provider": "anthropic",
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "baseUrl": null,
+  "model": "claude-3-5-sonnet-20241022",
+  "maxTokens": 4096,
+  "pollIntervalMs": 3000,
+  "maxHistoryPerConversation": 20,
+  "maxToolIterations": 10,
+  "sendProcessingIndicator": true,
+  "systemPrompt": "可选的自定义系统提示词",
+  "projectDir": "/Users/你的用户名/project",
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名"]
+    },
+    "shell": {
+      "command": "npx",
+      "args": ["-y", "mcp-shell-server"]
+    }
+  },
+  "safety": {
+    "requireConfirmation": false,
+    "allowedTools": null,
+    "blockedTools": [],
+    "blockedCommands": ["rm -rf /", "sudo"],
+    "readOnly": false
+  }
+}
+```
+
+### 支持的模型后端
+
+| 后端 | `provider` 值 | 说明 |
+| ------ | -------------- | ------ |
+| Anthropic / Claude | `anthropic` 或 `claude` | 原生支持 thinking blocks |
+| OpenAI | `openai` | 官方 API |
+| DeepSeek | `deepseek` | OpenAI 兼容接口 |
+| Kimi | `kimi` | OpenAI 兼容接口 |
+| 任意 OpenAI 兼容模型 | `openai` | 设置 `baseUrl` 即可 |
+
+### 环境变量
+
+| 变量 | 说明 |
+| ------ | ------ |
+| `IMESSAGE_DB_PATH` | 自定义 `chat.db` 路径 |
+| `IMESSAGE_MASTER_HANDLE` | Bridge 模式的主用户 iMessage 账号 |
+| `IMESSAGE_PROVIDER` | 默认 LLM 后端 |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | API 密钥 |
+| `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` | 自定义 API 端点 |
+
+配置文件支持 `${VAR_NAME}` 语法引用环境变量。
+
+---
+
+## MCP 工具（Server 模式）
+
+### `send_imessage`
+
+发送一条 iMessage。
+
+```json
+{ "recipient": "example@icloud.com", "text": "Hello from MCP!" }
+```
+
+### `list_conversations`
+
+列出最近会话。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `limit` | number | 20 | 最大返回会话数（最大 100） |
+
+### `read_conversation`
+
+读取某个会话的消息。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ------ | ------ | -------- | ------ |
+| `handle` | string | — | 按邮箱/手机号过滤 |
+| `chat_id` | number | — | 按 chat ROWID 过滤 |
+| `limit` | number | 30 | 最大返回消息数（最大 200） |
+| `before_id` | number | — | 分页：返回该 ROWID 之前的消息 |
+| `include_read` | boolean | true | 包含已读消息 |
+| `unread_only` | boolean | false | 仅返回未读消息 |
+
+### `get_new_messages`
+
+轮询最近收到的消息。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ------ | ------ | -------- | ------ |
+| `since` | string | — | ISO 时间戳 |
+| `max_results` | number | 10 | 最大返回消息数（最大 100） |
+| `unread_only` | boolean | false | 仅返回未读消息 |
+
+---
+
+## Bridge 工具
+
+Bridge 模式下，AI 可以使用所有已配置 MCP Server 提供的工具，外加两个内置本地工具：
+
+- `send_imessage` — 向任意收件人发送消息
+- `send_long_reply` — 把长回复拆成多条 iMessage 发送
+
+---
+
+## 安全说明
+
+- 所有读取操作都以**只读模式**打开 `chat.db`，不会修改数据库。
+- Bridge 模式只处理 `masterHandle` 发来的消息，其他人完全忽略。
+- 使用 `safety.readOnly: true` 可禁用写入类工具。
+- 使用 `safety.allowedTools` 可白名单限制可调用的工具。
+- 使用 `safety.blockedCommands` 可黑名单拦截危险命令。
+- 所有聊天数据留在你的 Mac 上；只有调用 LLM 后端的请求会离开本机。
+
+---
+
+## 常见问题
+
+| 问题 | 解决方法 |
+| ------ | --------- |
+| ❌ 找不到 iMessage 数据库 | 确认已在「信息」App 登录；或通过 `IMESSAGE_DB_PATH` 指定路径。 |
+| 🔒 读取数据库权限不足 | 给终端/IDE 开启「完全磁盘访问权限」。 |
+| 🔐 提示 "Database is locked" | 完全退出「信息」App，或等待同步完成。 |
+| 💻 osascript 执行失败 | 确认「信息」App 已运行并登录 Apple ID。 |
+| ⚠️ better-sqlite3 编译失败 | 运行 `xcode-select --install` 后重试。 |
+| 🐢 首次 `npx` 运行很慢 | 首次会下载并编译原生模块，后续会缓存。 |
+
+---
+
+## 许可证
+
+MIT © 2026 tinyxia

package/bin/imessage-mcp-server

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+await main();