Skip to main content
Glama
mcp-signal

mcp-signal

mcp-signal

Python uv MCP License: MIT GitHub issues GitHub stars Sealjay/mcp-signal MCP server

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トランスポート

Related MCP server: Signal MCP

セットアップ

前提条件

  • 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

オプションの環境変数:

変数

用途

SIGNAL_CLI_PATH

signal-cli バイナリパスの上書き

SIGNAL_DATA_DIR

Signal Desktopデータディレクトリの上書き

SIGNAL_DB_PASSWORD

必要に応じて暗号化されたデスクトップDBのパスワード

SIGNAL_DB_KEY

必要に応じて暗号化されたデスクトップDBの生キー

シェルで設定された環境変数は .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"]
    }
  }
}

アーキテクチャ

コンポーネント

説明

MCPサーバー

Python/FastMCP, stdioトランスポート

読み取りパス

ローカルのSignal Desktopデータベースを読み取る signal-export

送信パス

必要に応じて起動される signal-cli JSON-RPC

状態

個別のキャッシュなし。Signal Desktopデータから直接読み取り

データフロー

  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

ツール

ツール

用途

list_chats

Signal Desktopからのダイレクトチャットおよびグループチャットの一覧表示

read_messages

特定のチャットのメッセージを読み取る

search_messages

特定のチャット内またはすべてのチャットを横断してメッセージを検索する

list_groups

グループIDを含む signal-cli からのグループ一覧表示

send_message

ダイレクトな宛先またはグループへのテキストメッセージ送信

get_status

デスクトップDB / signal-cli / アカウントの準備状況を表示

プライバシーとセキュリティ

  • クラウド中継なし。ネットワークリスナーなし。すべてのデータはマシン上に留まります。

  • 読み取り/検索はローカルの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 を参照してください。

Available Tools

9 tools
chat_activityChat ActivityA
Read-onlyIdempotent

List Signal chats ranked by recent activity, showing last message date, last reply date, and count of unanswered inbound messages.

Read-only with no side effects. Use this to identify chats that need a response. Use list_chats instead for a general chat directory with message previews.

Inputs: limit. Returns: result

decrypt_attachmentDecrypt AttachmentA

Decrypt a locally stored Signal attachment and return the path to the decrypted file.

The encrypted_path and local_key values come from attachment metadata in read_messages or search_messages results. Read-only on Signal data; writes a decrypted copy to a temporary directory (the temp file is not auto-cleaned). Returns the absolute path to the decrypted file as a string on success, or a string starting with 'Error:' on failure (missing file, wrong key length, or HMAC mismatch). Use this after reading messages that contain attachments.

Inputs: local_key (required), encrypted_path (required). Returns: result

get_statusGet StatusA
Read-onlyIdempotent

Check whether the Signal MCP server can read local messages and send outbound messages.

Returns boolean fields: source_dir_exists, signal_cli_available, signal_account_configured, read_available, send_available. Read-only with no side effects. Call this before read or send operations to verify configuration; call pairing_status instead to check first-run device-linking state.

Inputs: no named parameters. Returns: object

list_chatsList ChatsA
Read-onlyIdempotent

List direct and group Signal chats from the local desktop database, sorted by most recent message.

Each result includes name, phone number, message count, and a preview of the last message. Read-only with no side effects. Use this to discover exact chat names before calling read_messages or search_messages. Use list_groups instead when you need group_id values for send_message.

Inputs: limit, query. Returns: result

list_groupsList GroupsA
Read-onlyIdempotent

List Signal groups with group_id, name, description, members, and admin lists, sorted alphabetically.

Read-only with no side effects. Queries signal-cli when available; falls back to the local desktop database (without group_id). Use this to obtain group_id values needed by send_message. Use list_chats instead for a combined view of both direct and group chats.

Inputs: limit, query. Returns: result

pairing_statusPairing StatusA

Report the Signal device-linking setup state for first-run pairing, so a client can surface the live link QR.

Returns a setup_state envelope: state 'ready' with the linked account once signal-cli is linked; 'awaiting_qr' with a 'qr_payload' sgnl://linkdevice URI to scan in Signal (Settings → Linked devices → Link new device) while a link is in progress (no payload yet on the first call, until the URI is captured); or 'error' when signal-cli is unavailable. Read-only from the caller's view, but the first call on an unlinked device starts a background signal-cli link process as a side effect. Poll this to drive a pairing UI; call get_status instead to check read/send availability once linked.

Inputs: no named parameters. Returns: object

read_messagesRead MessagesA
Read-onlyIdempotent

Read messages from a single Signal chat, returned newest-first.

Each message includes sender, date, body text, reactions, and attachment metadata. Read-only with no side effects. Requires an exact chat name from list_chats. Use search_messages instead to find messages by keyword across chats.

Inputs: chat_name (required), after, limit, before, +1 more. Returns: result

search_messagesSearch MessagesA
Read-onlyIdempotent

Search Signal message bodies for a keyword, within one chat or across all chats, returned newest-first.

Each result includes sender, date, chat name, body text, reactions, and attachment metadata. Read-only with no side effects. Use this to find messages by content. Use read_messages instead to browse a specific chat chronologically.

Inputs: query (required), limit, chat_name. Returns: result

send_messageSend MessageA

Send a text message via Signal to a direct recipient or group.

This is a write operation that delivers a real message through signal-cli. Sends are not reversible from this server — Signal supports user-initiated message deletion only via the official clients. Exactly one of phone_number, group_id, or chat_name must be supplied; providing zero or more than one raises an error. Rate-limited to 1 message per recipient per second and 10 messages per 60-second window globally. Requires signal-cli and SIGNAL_ACCOUNT to be configured — call get_status first to verify send_available is true. Returns target_type, target identifier, and timestamp on success.

Inputs: message (required), group_id, chat_name, phone_number. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a narrow, distinct purpose, and descriptions explicitly route the agent elsewhere when overlap exists (e.g. chat_activity vs list_chats, read_messages vs search_messages, get_status vs pairing_status). The only natural overlap is list_chats also covering groups, but list_groups is clearly framed as the source of group_id values. An agent should never misselect here.

    Naming Consistency4/5

    Most tools follow a clean verb_noun pattern (list_chats, read_messages, search_messages, send_message, decrypt_attachment). Two names deviate by dropping the verb (chat_activity, pairing_status), where get_ is implied by analogy with get_status. Minor and still readable.

    Tool Count5/5

    Nine tools is well-scoped for a Signal read/send bridge: discovery, reading, search, activity triage, attachment decryption, diagnostic/pairing state, and one write path. No obviously redundant or filler tools.

    Completeness4/5

    Core lifecycle is covered: discover chats/groups, read and search messages, decrypt attachments, check configuration/pairing, and send text messages. Gaps remain on the write side — no sending attachments, no group creation/management, no message deletion — though these are reasonable scope limits rather than dead ends for the stated read-focused purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Signal via signal-cli that enables sending and receiving messages, managing contacts and groups, and reacting over stdio.
      8 npm
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for a local-first messaging workspace that integrates Google Messages, WhatsApp, and Signal. It enables reading, sending, searching messages, and managing conversations through MCP tools.
      73
      -