signal-mcp

Signal Desktopの暗号化されたSQLiteデータベースを直接読み取り、オリジナルのPython版 signal-mcp-server よりも高度なクエリツールを提供するNode/TypeScript製の MCP サーバーです。

読み取り専用。 データベースは readonly: true および query_only=ON で開かれます。サーバーがSignalのデータを変更することはありません。

要件

• macOS（Signal Desktopがインストールされており、少なくとも一度サインインしていること）。

• Node.js 20以上。

• 初回実行時にmacOSキーチェーンのプロンプトが表示されます。承認してください（今後確認を求められたくない場合は「常に許可」にチェックを入れてください）。サーバーはログインキーチェーンからSignalの safeStorage パスワードを読み取り、SQLCipherキーを復号します。

Related MCP server: Cursor DB MCP Server

インストール

オプションA — GitHubからインストール（推奨）

npm経由でグローバルにインストールします。リポジトリの prepare スクリプトが自動的に tsc を実行するため、ビルド済みの dist/ は不要です。

npm install -g git+https://github.com/jagypus/signal-mcp.git

次に、Claude Codeに登録します：

claude mcp add signal --scope user -- signal-mcp

以上です。Claude Codeを開いて次のように試してみてください："List my Signal chats."（Signalのチャットを一覧表示して）

後でアップデートする場合：

npm install -g git+https://github.com/jagypus/signal-mcp.git

削除する場合：

claude mcp remove signal
npm uninstall -g signal-mcp

オプションB — クローンしてビルド（開発用）

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build
claude mcp add signal --scope user -- node "$(pwd)/dist/index.js"

オプションC — 手動設定

MCP設定を直接編集したい場合は、Claude CodeのMCPサーバー設定（例: ~/.claude.json の mcpServers ブロック、またはプロジェクトの .mcp.json）に以下を追加してください：

{
  "mcpServers": {
    "signal": {
      "command": "signal-mcp"
    }
  }
}

…または、クローンしたリポジトリのパスを使用する場合：

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

確認

claude mcp list

リストに signal が表示されるはずです。Claude Codeが既に実行中の場合は再起動し、チャットの一覧表示を依頼してください。

ツール

すべての入力はZodで検証されます。タイムスタンプはISO 8601形式で入出力されます。

フィルタリングルール

• exclude_system (デフォルト true) は type IN ('incoming','outgoing') のみを保持し、keychange、profile-change、group-v2-change、timer-notification などを除外します。

• only_with_body (デフォルト true) は body IS NULL である添付ファイルのみ/リアクション/スタンプの行を除外します。

• sender: me (送信済み)、them (受信済み)、any (両方)。

開発

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build               # compile to dist/
npm run dev                 # tsx, stdio (no build step)
npm run probe               # dump schema/FTS/types against the live DB
npx tsx scripts/smoke.ts    # exercise every tool against the live DB

データベースの開き方

macOS上のSignal Desktopは、SQLCipher v4データベースを ~/Library/Application Support/Signal/sql/db.sqlite に保存します。最近のSignalバージョンでは、SQLCipherキーはElectronの safeStorage を使用して config.json 内の encryptedKey に暗号化されて保存されています：

• v10/v11 プレフィックスを削除 → AES-128-CBC暗号文。

• 暗号化キー = PBKDF2-HMAC-SHA1(password, "saltysalt", 1003回反復, 16バイト)。

• macOSでは、password は security find-generic-password -s "Signal Safe Storage" -a "Signal" -w を介して取得されます（初回のみキーチェーンのプロンプトが表示されます）。

• IVは 0x20 の16バイトです。

平文は64文字の16進数SQLCipherキーです。config.json に平文の key が含まれる古いSignalビルドもサポートされています。

データベースは better-sqlite3-multiple-ciphers を使用して readonly: true モードで開かれ、念のため query_only=ON が設定されます。SQLCipherはWALを使用しているため、Signal Desktopの実行中に開いても問題ありません。

検索に関する注意点

messages_fts は存在しますが、Signal Desktopのネイティブコードでのみ登録されるカスタムの signal_tokenizer を使用しています。サードパーティのリーダーはそれに対して MATCH クエリを実行できないため、search_messages は一度試行し、失敗した場合は自動的に body LIKE '%query%' にフォールバックします。

環境変数

クロスプラットフォームに関する注意点

• macOS: 対応済み。

• Linux: safeStorage v10はリテラルパスワード peanuts を使用します。v11 (libsecret/KWallet) は未実装です。SIGNAL_KEY を明示的に設定してください。

• Windows: 未実装です。SIGNAL_KEY を明示的に設定してください。

プロジェクト構成

src/
  index.ts             # MCP server bootstrap
  db.ts                # connection + safeStorage key decryption
  schema.ts            # zod input shapes
  util/
    time.ts            # iso <-> ms
    messages.ts        # row shaping, display name resolution
    sql.ts             # shared filter SQL
  tools/
    listChats.ts
    getRecentMessages.ts
    getChatMessages.ts
    searchMessages.ts
    querySql.ts
scripts/
  probe.ts             # live-DB schema dump
  smoke.ts             # live-DB end-to-end check

ライセンス

MIT — LICENSE を参照してください。

このプロジェクトはSignal Messenger LLCと提携しておらず、承認も受けていません。 Signal Desktop自体はAGPL-3.0の下でライセンスされています。このプロジェクトはSignalのコードを再配布または変更するものではなく、ユーザー自身のマシン上でSignal Desktopが作成したローカルのSQLiteデータベースを読み取るだけです。