signal-mcp

一个 Node/TypeScript MCP 服务器，可直接读取 Signal Desktop 的加密 SQLite 数据库，并提供比原版 Python signal-mcp-server 更丰富的查询工具。

只读。 数据库以 readonly: true 和 query_only=ON 模式打开。服务器无法修改 Signal 的数据。

要求

• macOS，已安装 Signal Desktop 且至少登录过一次。

• Node.js 20+。

• 首次运行时，你会看到一个 macOS 钥匙串提示 —— 请批准它（如果你不想再次被询问，请勾选始终允许）。服务器会从你的登录钥匙串中读取 Signal safeStorage 密码，以解密 SQLCipher 密钥。

Related MCP server: Cursor DB MCP Server

安装

选项 A — 从 GitHub 安装（推荐）

通过 npm 全局安装。仓库的 prepare 脚本会自动运行 tsc，因此你不需要预构建的 dist/。

npm install -g git+https://github.com/jagypus/signal-mcp.git

然后向 Claude Code 注册：

claude mcp add signal --scope user -- signal-mcp

就是这样。打开 Claude Code 并尝试：“列出我的 Signal 聊天记录。”

稍后更新：

npm install -g git+https://github.com/jagypus/signal-mcp.git

卸载：

claude mcp remove signal
npm uninstall -g signal-mcp

选项 B — 克隆并构建（用于开发）

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build
claude mcp add signal --scope user -- node "$(pwd)/dist/index.js"

选项 C — 手动配置

如果你更喜欢直接编辑 MCP 配置，请将其添加到你的 Claude Code MCP 服务器配置中（例如 ~/.claude.json 的 mcpServers 块，或项目 .mcp.json）：

{
  "mcpServers": {
    "signal": {
      "command": "signal-mcp"
    }
  }
}

……或者，对于克隆的仓库路径：

{
  "mcpServers": {
    "signal": {
      "command": "node",
      "args": ["/absolute/path/to/signal-mcp/dist/index.js"]
    }
  }
}

验证

claude mcp list

你应该能在列表中看到 signal。如果 Claude Code 已经在运行，请重启它，然后要求它列出你的聊天记录。

工具

所有输入均通过 Zod 进行验证。时间戳采用 ISO 8601 格式输入/输出。

过滤规则

• exclude_system (默认 true) 仅保留 type IN ('incoming','outgoing')，过滤掉 keychange、profile-change、group-v2-change、timer-notification 等。

• only_with_body (默认 true) 排除 body IS NULL 的仅附件/反应/贴纸行。

• sender: me (发送), them (接收), any (两者)。

开发

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build               # compile to dist/
npm run dev                 # tsx, stdio (no build step)
npm run probe               # dump schema/FTS/types against the live DB
npx tsx scripts/smoke.ts    # exercise every tool against the live DB

数据库打开方式

macOS 上的 Signal Desktop 将 SQLCipher v4 数据库存储在 ~/Library/Application Support/Signal/sql/db.sqlite。现代 Signal 版本使用 Electron 的 safeStorage 将 SQLCipher 密钥加密存储在 config.json 的 encryptedKey 中：

• 去除 v10/v11 前缀 → AES-128-CBC 密文。

• 加密密钥 = PBKDF2-HMAC-SHA1(密码, "saltysalt", 1003 次迭代, 16 字节)。

• 在 macOS 上，密码 通过 security find-generic-password -s "Signal Safe Storage" -a "Signal" -w 获取（首次运行时会有一次钥匙串提示）。

• IV 为 16 字节的 0x20。

明文即为 64 字符的十六进制 SQLCipher 密钥。同时也支持 config.json 中包含明文 key 的旧版 Signal 构建。

数据库使用 better-sqlite3-multiple-ciphers 以 readonly: true 模式打开，并设置 query_only=ON 作为双重保险。在 Signal Desktop 运行时打开数据库不会有问题，因为 SQLCipher 使用了 WAL。

搜索注意事项

messages_fts 存在，但使用了 Signal 自定义的 signal_tokenizer，该分词器仅由 Signal Desktop 的原生代码注册。第三方读取器无法对其运行 MATCH 查询，因此 search_messages 会先探测一次，如果失败则静默回退到 body LIKE '%query%'。

环境变量

跨平台说明

• macOS：已处理。

• Linux：safeStorage v10 使用字面密码 peanuts。v11 (libsecret/KWallet) 尚未实现 —— 请显式设置 SIGNAL_KEY。

• Windows：尚未实现 —— 请显式设置 SIGNAL_KEY。

项目布局

src/
  index.ts             # MCP server bootstrap
  db.ts                # connection + safeStorage key decryption
  schema.ts            # zod input shapes
  util/
    time.ts            # iso <-> ms
    messages.ts        # row shaping, display name resolution
    sql.ts             # shared filter SQL
  tools/
    listChats.ts
    getRecentMessages.ts
    getChatMessages.ts
    searchMessages.ts
    querySql.ts
scripts/
  probe.ts             # live-DB schema dump
  smoke.ts             # live-DB end-to-end check

许可证

MIT — 见 LICENSE。

本项目不隶属于 Signal Messenger LLC，也不受其认可。Signal Desktop 本身采用 AGPL-3.0 许可；本项目不重新分发或修改任何 Signal 代码，仅读取 Signal Desktop 在你本地机器上创建的 SQLite 数据库。