mcp-signal
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トランスポート
Related MCP server: Signal MCP
セットアップ
前提条件
Python 3.13+
ローカルメッセージデータベースを持つSignal Desktop
送信を行いたい場合は、インストールおよびリンク済みの
signal-cli
インストール
リポジトリをクローンする
git clone https://github.com/Sealjay/mcp-signal.git cd mcp-signal依存関係をインストールする
uv syncsignal-cliをインストールする (オプション — 送信にのみ必要)macOSの場合、Homebrewが最も簡単です:
brew install signal-cli
送信設定
サーバーは、リポジトリルートに存在する場合、ローカルの .env.local ファイルを自動的に読み込みます。このファイルはgitの管理対象外であり、マシン固有の設定を行うのに推奨される場所です。
cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOFオプションの環境変数:
変数 | 用途 |
|
|
| Signal Desktopデータディレクトリの上書き |
| 必要に応じて暗号化されたデスクトップDBのパスワード |
| 必要に応じて暗号化されたデスクトップ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 smokeMCPクライアントの設定
すべてのクライアントは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 Desktopデータから直接読み取り |
データフロー
MCPクライアントがstdio経由で
signal-mcp serveを起動します。読み取り/検索ツールがローカルのSignal Desktopデータベースに対して
signal-exportを呼び出します。グループ一覧表示と送信は
signal-cli -a ACCOUNT jsonRpcを呼び出します。結果が構造化された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からのダイレクトチャットおよびグループチャットの一覧表示 |
| 特定のチャットのメッセージを読み取る |
| 特定のチャット内またはすべてのチャットを横断してメッセージを検索する |
| グループIDを含む |
| ダイレクトな宛先またはグループへのテキストメッセージ送信 |
| デスクトップDB / |
プライバシーとセキュリティ
クラウド中継なし。ネットワークリスナーなし。すべてのデータはマシン上に留まります。
読み取り/検索はローカルの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:uvPATH を参照してください。メッセージが返されない — Signal Desktopがインストールされており、メッセージ履歴があることを確認してください。読み取りパスはローカルのSignal Desktopデータベースを直接クエリします。
コントリビューション
プルリクエストによるコントリビューションを歓迎します。以下を行ってください:
プッシュ前に
uv run ruff check .を実行する。uv run pytestがパスすることを確認する。
完全な開発ワークフローについては CLAUDE.md を参照してください。
ライセンス
MITライセンス — LICENSE を参照してください。
Available Tools
9 toolschat_activityChat ActivityARead-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 StatusARead-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 ChatsARead-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 GroupsARead-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 MessagesARead-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 MessagesARead-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Unified messaging MCP server: WhatsApp, Instagram, Telegram, SMS, Messenger & email support inbox
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP Server for retrieving Signal messages using signal-export logic.8-
- AlicenseAqualityAmaintenanceThe most complete Signal MCP server and CLI.81279 PyPI13MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Signal via signal-cli that enables sending and receiving messages, managing contacts and groups, and reacting over stdio.8 npm-
- AlicenseNot gradedqualityBmaintenanceMCP 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-