mcp-signal

signal-export を介してローカルの暗号化データベースからSignal Desktopの履歴を読み取り、signal-cli を介してメッセージを送信するローカルModel Context Protocol (MCP) サーバーです。

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 ファイルを自動的に読み込みます。このファイルはgitの管理対象外であり、マシン固有の設定を行うのに推奨される場所です。

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

オプションの環境変数:

シェルで設定された環境変数は .env.local よりも優先されます。

signal-cli のリンク（初回実行時のみ）

mcp-signal 自体はリンクを管理しません。最初にローカルの signal-cli デバイスをリンクしてください:

signal-cli link -n "signal-mcp"

SignalモバイルアプリでQRコードをスキャンします（設定 → リンクされたデバイス → 新しいデバイスをリンク）。

現在の signal-cli バージョンでは、link に -a / --account を渡さないでください。新しいセカンダリデバイスをリンクする際に電話番号は必要ありません。

QRコードが承認されたら、リンクされたアカウントが表示されていることを確認します:

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インスタンスごとに1アカウント。

• グループ送信には signal-cli が必要: ローカルDBの読み取りだけでは、グループに安全に送信するための十分な情報が得られません。

開発

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" を実行し、携帯電話からQRコードをスキャンしてください。

• MCPクライアントがサーバーを起動できない — args には相対パスではなく、リポジトリへの絶対パスを含める必要があります。uv 自体が spawn uv ENOENT で失敗する場合は、macOS: uv PATH を参照してください。

• メッセージが返されない — Signal Desktopがインストールされており、メッセージ履歴があることを確認してください。読み取りパスはローカルのSignal Desktopデータベースを直接クエリします。

コントリビューション

プルリクエストによるコントリビューションを歓迎します。以下を行ってください:

• プッシュ前に uv run ruff check . を実行する。

• uv run pytest がパスすることを確認する。

完全な開発ワークフローについては CLAUDE.md を参照してください。

ライセンス

MITライセンス — LICENSE を参照してください。