mcp-signal

Ein lokaler Model Context Protocol (MCP)-Server, der den Signal Desktop-Verlauf aus der lokalen verschlüsselten Datenbank über signal-export liest und ausgehende Nachrichten über signal-cli sendet.

mcp-signal konzentriert sich auf den Kern-Workflow für persönliche Signal-Automatisierung – Chats auflisten, Nachrichten lesen, Nachrichten durchsuchen, Gruppen inspizieren und Nachrichten an Direkt- oder Gruppenchats senden. Alles läuft lokal; stdio-Transport ohne Netzwerk-Listener.

Hinweis – gemischtes Backend. Lesen/Suchen erfolgt aus der lokalen Signal Desktop-Datenbank. Das Senden verwendet signal-cli, das separat installiert und mit einem Signal-Konto verknüpft sein muss. Wenn signal-cli nicht verfügbar ist, funktionieren Lesen/Suchen weiterhin, aber die Sende-Tools nicht.

Funktionen

• Auflisten von Direkt- und Gruppenchats aus Signal Desktop

• Lesen aktueller Nachrichten aus einem Chat

• Suchen von Nachrichten innerhalb eines Chats oder über alle Chats hinweg

• Auflisten von Gruppenchats mit signal-cli-Gruppen-IDs für die Verwendung beim Senden

• Senden einer Nachricht an:

  • einen direkten Empfänger per Telefonnummer

  • eine Gruppe per Gruppen-ID

  • einen Chat per exaktem Chat-Namen (mit Mehrdeutigkeitsprüfungen)

• Läuft vollständig auf Ihrem Rechner; stdio-Transport ohne Netzwerk-Listener

Einrichtung

Voraussetzungen

• Python 3.13+

• uv

• Signal Desktop mit einer bestehenden lokalen Nachrichtendatenbank

• signal-cli installiert und verknüpft, falls Sie ausgehende Nachrichten senden möchten

Installation

1. Klonen Sie dieses Repository

   git clone https://github.com/Sealjay/mcp-signal.git
   cd mcp-signal

2. Abhängigkeiten installieren

   uv sync

3. signal-cli installieren (optional – nur für ausgehende Nachrichten erforderlich)

   Unter macOS ist der einfachste Weg Homebrew:

   brew install signal-cli

Ausgehende Nachrichten konfigurieren

Der Server lädt automatisch eine lokale .env.local-Datei aus dem Repository-Stammverzeichnis, falls vorhanden. Diese Datei ist in gitignore enthalten und ist der empfohlene Ort für maschinenlokale Konfigurationen.

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

Optionale Umgebungsvariablen:

Umgebungsvariablen, die in der Shell gesetzt sind, haben Vorrang vor .env.local.

signal-cli verknüpfen (nur beim ersten Start)

mcp-signal verwaltet die Verknüpfung nicht selbst. Verknüpfen Sie zuerst das lokale signal-cli-Gerät:

signal-cli link -n "signal-mcp"

Scannen Sie den QR-Code in der Signal-Mobil-App (Einstellungen → Verknüpfte Geräte → Neues Gerät verknüpfen).

Übergeben Sie bei aktuellen signal-cli-Versionen nicht -a / --account an link – das Verknüpfen eines neuen sekundären Geräts erfordert dort keine Telefonnummer.

Nachdem der QR-Code akzeptiert wurde, bestätigen Sie, dass das verknüpfte Konto sichtbar ist:

signal-cli listAccounts

Dieses Konto sollte mit dem Wert SIGNAL_ACCOUNT in .env.local übereinstimmen.

signal-cli speichert seinen Status des verknüpften Kontos unter seinem eigenen lokalen Datenverzeichnis (normalerweise ~/.local/share/signal-cli/data unter macOS/Linux). Dieser Status befindet sich außerhalb dieses Repositorys und wird nicht von mcp-signal committet.

Überprüfen Sie, ob alles verbunden ist:

uv run signal-mcp smoke

MCP-Client-Konfiguration

Alle Clients starten den Server auf die gleiche Weise über stdio. Unter macOS benötigen Sie möglicherweise den absoluten Pfad zu uv – siehe macOS: uv PATH unten.

Claude Code

Der schnellste Weg ist die CLI:

claude mcp add --transport stdio signal --scope user -- uv run --directory /absolute/path/to/mcp-signal signal-mcp serve

Alternativ fügen Sie dies zu .mcp.json in Ihrem Projektstammverzeichnis hinzu (oder ~/.claude.json für einen benutzerspezifischen Server):

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Wenn Sie die Datei direkt bearbeiten, starten Sie die Claude Code-Sitzung neu, um die Änderungen zu übernehmen.

Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hinzu:

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Starten Sie Claude Desktop neu. Sie sollten signal als verfügbare Integration sehen.

Cursor

Fügen Sie dies zu ~/.cursor/mcp.json hinzu:

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Starten Sie Cursor neu.

macOS: uv PATH

GUI-Apps (Claude Desktop, Cursor) erben nicht immer den PATH von Ihrem interaktiven Terminal, daher kann uv mit spawn uv ENOENT fehlschlagen. Beheben Sie dies, indem Sie den absoluten Pfad zu uv in command verwenden:

• Homebrew — /opt/homebrew/bin/uv (Apple Silicon) oder /usr/local/bin/uv (Intel)

• Manuelle Installation — führen Sie which uv in Ihrem Terminal aus, um ihn zu finden

Beispiel:

{
  "mcpServers": {
    "signal": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Architektur

Datenfluss

1. Der MCP-Client startet signal-mcp serve über stdio.

2. Lese-/Such-Tools rufen signal-export gegen die lokale Signal Desktop-Datenbank auf.

3. Gruppenauflistung und ausgehende Nachrichten rufen signal-cli -a ACCOUNT jsonRpc auf.

4. Ergebnisse werden als strukturiertes JSON zurückgegeben.

Projektstruktur

mcp-signal/
  src/mcp_signal/
    config.py
    main.py
    reader.py
    server.py
    signal_cli.py
  tests/
  CLAUDE.md
  LICENSE
  README.md
  SECURITY.md

Tools

Datenschutz und Sicherheit

• Kein Cloud-Relay. Kein Netzwerk-Listener. Alle Daten bleiben auf Ihrem Rechner.

• Lesen/Suchen verwendet nur Ihre lokalen Signal Desktop-Daten.

• Sendeoperationen erfordern ein lokal konfiguriertes signal-cli-Konto.

• .env.local ist für lokale Geheimnisse wie SIGNAL_ACCOUNT gedacht und wird nicht committet.

• Der Status des verknüpften signal-cli-Geräts wird in seinem eigenen lokalen App-Datenverzeichnis außerhalb dieses Repositorys gespeichert und nicht committet.

Siehe SECURITY.md, wie Schwachstellen gemeldet werden können.

Einschränkungen

• Prompt-Injection-Risiko: Wie bei vielen MCP-Servern unterliegt dieser der tödlichen Triade. Bösartige eingehende Nachrichten könnten versuchen, einen Agenten anzuweisen, andere Nachrichten zu exfiltrieren. Behandeln Sie die Tool-Oberfläche entsprechend und überprüfen Sie ausgehende Aktionen, bevor Sie sie genehmigen.

• Gemischtes Backend: Der Chatverlauf stammt von Signal Desktop, während ausgehende Nachrichten von signal-cli stammen.

• Keine Anhänge: Nur Textversand.

• Keine Echtzeit-Benachrichtigungen: Nur Polling/Lesen.

• Ein Konto pro MCP-Instanz.

• Gruppensendungen benötigen signal-cli: Lokale DB-Lesevorgänge allein liefern nicht genügend Informationen, um sicher an Gruppen zu senden.

Entwicklung

uv sync
uv run signal-mcp smoke
uv run pytest
uv run ruff check .

Fehlerbehebung

• signal-cli nicht gefunden — bestätigen Sie, dass signal-cli im PATH ist oder setzen Sie SIGNAL_CLI_PATH in .env.local. Unter macOS ist brew install signal-cli der einfachste Weg.

• Lesen/Suchen funktioniert, aber Senden schlägt fehl — signal-cli ist nicht verknüpft oder SIGNAL_ACCOUNT ist nicht gesetzt. Führen Sie signal-cli listAccounts zur Überprüfung aus und prüfen Sie dann .env.local.

• signal-cli link hängt oder schlägt fehl — übergeben Sie bei aktuellen Versionen kein -a / --account an link. Führen Sie signal-cli link -n "signal-mcp" aus und scannen Sie den QR-Code von Ihrem Telefon.

• MCP-Client kann den Server nicht starten — args muss einen absoluten Pfad zum Repository enthalten, nicht relativ. Wenn uv selbst mit spawn uv ENOENT fehlschlägt, siehe macOS: uv PATH.

• Keine Nachrichten zurückgegeben — bestätigen Sie, dass Signal Desktop installiert ist und einen Nachrichtenverlauf hat. Der Lesepfad fragt die lokale Signal Desktop-Datenbank direkt ab.

Mitwirken

Beiträge sind per Pull Request willkommen. Bitte:

• Führen Sie uv run ruff check . vor dem Pushen aus.

• Stellen Sie sicher, dass uv run pytest erfolgreich ist.

Siehe CLAUDE.md für den vollständigen Entwicklungsworkflow.

Lizenz

MIT-Lizenz – siehe LICENSE.