signal-mcp

Ein Node/TypeScript MCP-Server, der die verschlüsselte SQLite-Datenbank von Signal Desktop direkt liest und umfangreichere Abfragewerkzeuge bereitstellt als der ursprüngliche Python signal-mcp-server.

Schreibgeschützt. Die Datenbank wird mit readonly: true und query_only=ON geöffnet. Der Server kann die Daten von Signal nicht verändern.

Anforderungen

• macOS, mit installiertem Signal Desktop und mindestens einmal angemeldet.

• Node.js 20+.

• Beim ersten Start sehen Sie eine macOS-Schlüsselbund-Abfrage — bestätigen Sie diese (und aktivieren Sie Immer erlauben, falls Sie nicht erneut gefragt werden möchten). Der Server liest das Signal safeStorage-Passwort aus Ihrem Anmelde-Schlüsselbund, um den SQLCipher-Schlüssel zu entschlüsseln.

Related MCP server: Cursor DB MCP Server

Installation

Option A — Installation von GitHub (empfohlen)

Globale Installation via npm. Das prepare-Skript des Repos führt tsc automatisch aus, sodass Sie kein vorgefertigtes dist/ benötigen.

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

Registrieren Sie es dann bei Claude Code:

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

Das war's. Öffnen Sie Claude Code und versuchen Sie: "List my Signal chats."

Zum späteren Aktualisieren:

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

Zum Entfernen:

claude mcp remove signal
npm uninstall -g signal-mcp

Option B — Klonen und Bauen (für die Entwicklung)

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"

Option C — Manuelle Konfiguration

Wenn Sie Ihre MCP-Konfiguration lieber direkt bearbeiten möchten, fügen Sie dies zu Ihrer Claude Code MCP-Server-Konfiguration hinzu (z. B. mcpServers-Block in ~/.claude.json oder eine Projekt-.mcp.json):

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

…oder für den Pfad des geklonten Repos:

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

Überprüfung

claude mcp list

Sie sollten signal in der Liste sehen. Starten Sie Claude Code neu, falls es bereits lief, und bitten Sie es dann, Ihre Chats aufzulisten.

Werkzeuge

Alle Eingaben werden mit Zod validiert. Zeitstempel sind ISO 8601 ein-/ausgehend.

Filterregeln

• exclude_system (Standard true) behält nur type IN ('incoming','outgoing') bei und filtert keychange, profile-change, group-v2-change, timer-notification usw. heraus.

• only_with_body (Standard true) schließt Zeilen aus, die nur Anhänge / Reaktionen / Sticker enthalten, bei denen body IS NULL ist.

• sender: me (ausgehend), them (eingehend), any (beide).

Entwicklung

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

Wie die Datenbank geöffnet wird

Signal Desktop auf macOS speichert die SQLCipher v4-Datenbank unter ~/Library/Application Support/Signal/sql/db.sqlite. Moderne Signal-Versionen speichern den SQLCipher-Schlüssel verschlüsselt in config.json unter encryptedKey mittels Electrons safeStorage:

• Entfernen des v10/v11-Präfixes → AES-128-CBC-Geheimtext.

• Verschlüsselungsschlüssel = PBKDF2-HMAC-SHA1(Passwort, "saltysalt", 1003 Iterationen, 16 Bytes).

• Unter macOS wird das Passwort über security find-generic-password -s "Signal Safe Storage" -a "Signal" -w abgerufen (eine Schlüsselbund-Abfrage beim ersten Mal).

• IV sind 16 Bytes von 0x20.

Der Klartext ist der 64-stellige hexadezimale SQLCipher-Schlüssel. Ältere Signal-Builds mit einem Klartext-key in config.json werden ebenfalls unterstützt.

Die Datenbank wird mit better-sqlite3-multiple-ciphers im Modus readonly: true geöffnet und query_only=ON ist als zusätzliche Absicherung gesetzt. Das Öffnen während Signal Desktop läuft funktioniert problemlos, da SQLCipher WAL verwendet.

Such-Einschränkung

messages_fts existiert, verwendet aber den benutzerdefinierten signal_tokenizer von Signal, der nur vom nativen Code von Signal Desktop registriert wird. Reader von Drittanbietern können keine MATCH-Abfragen dagegen ausführen, daher prüft search_messages dies einmal und fällt stillschweigend auf body LIKE '%query%' zurück.

Umgebung

Plattformübergreifende Hinweise

• macOS: unterstützt.

• Linux: safeStorage v10 verwendet das wörtliche Passwort peanuts. v11 (libsecret/KWallet) ist nicht implementiert — setzen Sie SIGNAL_KEY explizit.

• Windows: nicht implementiert — setzen Sie SIGNAL_KEY explizit.

Projektstruktur

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

Lizenz

MIT — siehe LICENSE.

Dieses Projekt ist nicht mit Signal Messenger LLC verbunden oder von dieser unterstützt. Signal Desktop selbst ist unter AGPL-3.0 lizenziert; dieses Projekt verbreitet oder modifiziert keinen Signal-Code, es liest lediglich die lokale SQLite-Datenbank, die Signal Desktop auf Ihrem eigenen Rechner erstellt.