signal-mcp

一个面向 Signal Desktop 消息的本地、只读 Model Context Protocol 服务器。

它为支持 MCP 的代理提供四个范围狭窄的工具：

• signal_list_conversations — 查找最近的单聊和群组对话，不返回消息正文。

• signal_get_messages — 从某个确切的对话中检索按时间排序且数量受限的消息窗口。

• signal_search_messages — 字面子串搜索，可按对话和时间进行范围限定。

• signal_get_message — 检索一条确切的消息，包含引用与附件元数据。

该服务器从不发送消息，也从不写入 Signal 的数据库。它通过 stdio 在本地运行，没有 HTTP 监听器。

重要隐私警告

此服务器会将你的私人 Signal 历史记录暴露给你所连接的任何 MCP 主机和模型。请审查该主机的数据处理政策，将请求范围限制在很窄的范围内，并且不要为你不信任的代理配置此服务器。

Signal Desktop 的本地数据库是实现细节，而非公开 API。Signal 的数据库结构更新可能会暂时破坏此项目。本项目是非官方的，与 Signal Messenger LLC 没有任何关联，也未获得其认可。

Related MCP server: msteams-local-mcp

当前支持

• Windows

• 同一 Windows 用户下安装了 Signal Desktop

• Node.js 20 或更高版本

• 本地 stdio MCP 主机

目前，自动密钥恢复需要 Windows，因为 Signal 使用当前用户的 DPAPI 凭据保护其 Chromium OSCrypt 主密钥。

安装

git clone https://github.com/NathanDai5287/signal-mcp.git
cd signal-mcp
npm install
npm run build

默认情况下，服务器会在 %APPDATA%\Signal 中查找 Signal。通常无需任何配置。

要在不配置 MCP 主机的情况下测试连接：

npx @modelcontextprotocol/inspector node dist/src/index.js

Inspector 可以调用会返回真实私密消息的工具。请相应地将它的浏览器会话视为敏感会话。

MCP 主机配置

构建项目，然后将你的主机配置为使用绝对路径启动编译后的入口点：

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

更改 MCP 配置后，请重启主机。确切的配置文件位置取决于主机。

可选配置

环境变量通过 MCP 主机的服务器配置传递：

避免将 SIGNAL_MCP_KEY 放入已提交的文件中。在 Windows 上，自动恢复更可取。

数据库访问工作原理

Signal Desktop 将经 AES-256-GCM 加密的 SQLCipher 密钥存储在 config.json 中。其包装密钥位于 Chromium 的 Local State 中，由 Windows DPAPI 保护。在启动时，此服务器：

1. 对当前 Windows 用户的 OSCrypt 主密钥进行 DPAPI 解保护。

2. 在内存中解密 Signal 的 SQLCipher 密钥。

3. 以 SQLCipher 兼容级别 4 打开数据库。

4. 在提供任何工具调用之前启用 SQLite 的 query_only 模式。

该密钥绝不会被打印、通过 MCP 返回，也不会由本项目持久化。

所有搜索输入都是绑定的 SQL 参数。%、_ 和 \ 会被转义，因此搜索词是字面子串，而不是调用方控制的 SQL 模式。每个结果集都有数量上限。

返回的数据

消息结果可能包含：

• Signal 消息和对话标识符

• 毫秒时间戳

• 接收/发送方向

• 发送者服务 ID 和显示名称

• 消息正文

• 反规范化的引用回复文本

• 附件元数据和本地下载可用性

此里程碑版本不会解密或返回附件字节，不会创建持久化存档，不会执行语义搜索，也不会发送消息。Signal 已删除的阅后即焚消息无法恢复。

开发

npm test
npm run check
npm run build

测试套件使用内存中的模拟读取器，不会访问你的 Signal 数据。仍需要手动进行本地冒烟测试，以检测 Signal 私有数据库结构的变化。

运行日志输出到 stderr，因为 stdout 保留用于 MCP JSON-RPC 通信。

安全

请不要在公开 issue 中包含消息文本、数据库文件、密钥、服务 ID、电话号码或本地路径。有关私下报告漏洞的指南，请参阅 SECURITY.md。

许可证

项目源代码采用 MIT 许可证。依赖项保留其各自的许可证；尤其是 @signalapp/sqlcipher 根据 AGPL-3.0-only 分发。