mcp-signal

一个本地模型上下文协议 (MCP) 服务器，通过 signal-export 从本地加密数据库读取 Signal Desktop 历史记录，并通过 signal-cli 发送出站消息。

mcp-signal 专注于个人 Signal 自动化的核心工作流——列出聊天、读取消息、搜索消息、检查群组以及向直接聊天或群组发送消息。所有操作均在本地运行；使用 stdio 传输，无网络监听。

注意——混合后端。 读取/搜索功能来自本地 Signal Desktop 数据库。发送功能使用 signal-cli，该工具必须单独安装并关联到 Signal 账户。如果 signal-cli 不可用，读取/搜索功能仍可正常工作，但发送工具将无法使用。

功能

• 从 Signal Desktop 列出直接聊天和群组聊天

• 读取聊天中的最近消息

• 在单个聊天或所有聊天中搜索消息

• 列出带有 signal-cli 群组 ID 的群组聊天，以便进行出站发送

• 发送消息至：

  • 通过电话号码发送给直接收件人

  • 通过群组 ID 发送给群组

  • 通过精确的聊天名称发送给聊天（带有歧义检查）

• 完全在您的机器上运行；使用 stdio 传输，无网络监听

设置

先决条件

• Python 3.13+

• uv

• 带有现有本地消息数据库的 Signal Desktop

• 如果需要出站发送，请安装并关联 signal-cli

安装

1. 克隆此仓库

   git clone https://github.com/Sealjay/mcp-signal.git
   cd mcp-signal

2. 安装依赖项

   uv sync

3. 安装 signal-cli（可选——仅在需要出站发送时才需要）

   在 macOS 上，最简单的方法是使用 Homebrew：

   brew install signal-cli

配置出站发送

如果存在，服务器会自动从仓库根目录加载本地 .env.local 文件。此文件已被 gitignore 忽略，是存放机器本地配置的推荐位置。

cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOF

可选环境变量：

在 shell 中设置的环境变量优先级高于 .env.local。

关联 signal-cli（仅限首次运行）

mcp-signal 本身不管理关联。请先关联本地 signal-cli 设备：

signal-cli link -n "signal-mcp"

在 Signal 移动应用中扫描二维码（设置 → 已关联设备 → 关联新设备）。

在当前的 signal-cli 版本中，请不要向 link 命令传递 -a / --account 参数——关联新的辅助设备时不需要电话号码。

二维码被接受后，确认已关联的账户可见：

signal-cli listAccounts

该账户应与 .env.local 中的 SIGNAL_ACCOUNT 值匹配。

signal-cli 将其关联账户状态存储在自己的本地数据目录下（macOS/Linux 上通常为 ~/.local/share/signal-cli/data）。该状态位于此仓库之外，且不会被 mcp-signal 提交。

验证一切连接正常：

uv run signal-mcp smoke

MCP 客户端配置

所有客户端都通过 stdio 以相同方式启动服务器。在 macOS 上，您可能需要 uv 的绝对路径——请参阅下方的 macOS: uv PATH。

Claude Code

最快的方法是使用 CLI：

claude mcp add --transport stdio signal --scope user -- uv run --directory /absolute/path/to/mcp-signal signal-mcp serve

或者，将其添加到项目根目录的 .mcp.json 中（或用户范围服务器的 ~/.claude.json 中）：

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

如果您直接编辑该文件，请重启 Claude Code 会话以使其生效。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

重启 Claude Desktop。您应该会看到 signal 列为可用的集成。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

重启 Cursor。

macOS: uv PATH

GUI 应用程序（Claude Desktop、Cursor）并不总是从您的交互式终端继承 PATH，因此 uv 可能会因 spawn uv ENOENT 而失败。通过在 command 中使用 uv 的绝对路径来修复：

• Homebrew — /opt/homebrew/bin/uv (Apple Silicon) 或 /usr/local/bin/uv (Intel)

• 手动安装 — 在终端运行 which uv 以查找路径

示例：

{
  "mcpServers": {
    "signal": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

架构

数据流

1. MCP 客户端通过 stdio 启动 signal-mcp serve。

2. 读取/搜索工具针对本地 Signal Desktop 数据库调用 signal-export。

3. 群组列表和出站发送调用 signal-cli -a ACCOUNT jsonRpc。

4. 结果以结构化 JSON 形式返回。

项目结构

mcp-signal/
  src/mcp_signal/
    config.py
    main.py
    reader.py
    server.py
    signal_cli.py
  tests/
  CLAUDE.md
  LICENSE
  README.md
  SECURITY.md

工具

隐私与安全

• 无云端中继。无网络监听。所有数据保留在您的机器上。

• 读取/搜索仅使用您的本地 Signal Desktop 数据。

• 发送操作需要本地配置的 signal-cli 账户。

• .env.local 旨在用于存放本地机密（如 SIGNAL_ACCOUNT），且不会被提交。

• signal-cli 关联设备状态存储在它自己的本地应用数据目录中，位于此仓库之外，且不会被提交。

请参阅 SECURITY.md 了解如何报告漏洞。

限制

• 提示注入风险： 与许多 MCP 服务器一样，此服务器也受到 the lethal trifecta 的影响。恶意的传入消息可能会尝试指示代理窃取其他消息。请相应地对待工具界面，并在批准出站操作前进行审查。

• 混合后端： 聊天记录来自 Signal Desktop，而出站发送来自 signal-cli。

• 无附件： 仅支持发送文本。

• 无实时通知： 仅支持轮询/读取。

• 每个 MCP 实例仅支持单个账户。

• 群组发送需要 signal-cli： 仅靠本地数据库读取无法提供安全发送到群组所需的信息。

开发

uv sync
uv run signal-mcp smoke
uv run pytest
uv run ruff check .

故障排除

• 找不到 signal-cli — 确认 signal-cli 在 PATH 中，或在 .env.local 中设置 SIGNAL_CLI_PATH。在 macOS 上，brew install signal-cli 是最简单的方法。

• 读取/搜索正常但发送失败 — signal-cli 未关联或未设置 SIGNAL_ACCOUNT。运行 signal-cli listAccounts 进行验证，然后检查 .env.local。

• signal-cli link 挂起或失败 — 在当前版本中，请勿向 link 传递 -a / --account 参数。运行 signal-cli link -n "signal-mcp" 并从手机扫描二维码。

• MCP 客户端无法启动服务器 — args 必须包含仓库的绝对路径，而不是相对路径。如果 uv 本身因 spawn uv ENOENT 而失败，请参阅 macOS: uv PATH。

• 未返回消息 — 确认已安装 Signal Desktop 并拥有消息历史记录。读取路径直接查询本地 Signal Desktop 数据库。

贡献

欢迎通过 Pull Request 贡献代码。请：

• 在推送前运行 uv run ruff check .。

• 确保 uv run pytest 通过。

请参阅 CLAUDE.md 了解完整的开发工作流。

许可证

MIT 许可证 — 请参阅 LICENSE。