mcp-signal
mcp-signal
Ein lokaler Model Context Protocol (MCP)-Server, der den Signal Desktop-Verlauf aus der lokalen verschlüsselten Datenbank über
signal-exportliest und ausgehende Nachrichten übersignal-clisendet.
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. Wennsignal-clinicht 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 SendenSenden 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
Related MCP server: Signal MCP
Einrichtung
Voraussetzungen
Python 3.13+
Signal Desktop mit einer bestehenden lokalen Nachrichtendatenbank
signal-cliinstalliert und verknüpft, falls Sie ausgehende Nachrichten senden möchten
Installation
Klonen Sie dieses Repository
git clone https://github.com/Sealjay/mcp-signal.git cd mcp-signalAbhängigkeiten installieren
uv syncsignal-cliinstallieren (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"
EOFOptionale Umgebungsvariablen:
Variable | Zweck |
| Pfad zur |
| Datenverzeichnis von Signal Desktop überschreiben |
| Passwort für verschlüsselte Desktop-Datenbanken, falls erforderlich |
| Rohschlüssel für verschlüsselte Desktop-Datenbanken, falls erforderlich |
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 listAccountsDieses 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 smokeMCP-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 serveAlternativ 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 uvin 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
Komponente | Beschreibung |
MCP-Server | Python/FastMCP, stdio-Transport |
Lesepfad |
|
Sendepfad |
|
Status | Kein separater Cache; liest direkt aus Signal Desktop-Daten |
Datenfluss
Der MCP-Client startet
signal-mcp serveüber stdio.Lese-/Such-Tools rufen
signal-exportgegen die lokale Signal Desktop-Datenbank auf.Gruppenauflistung und ausgehende Nachrichten rufen
signal-cli -a ACCOUNT jsonRpcauf.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.mdTools
Tool | Zweck |
| Direkt- und Gruppenchats aus Signal Desktop auflisten |
| Nachrichten aus einem bestimmten Chat lesen |
| Nachrichten innerhalb eines Chats oder über alle Chats hinweg suchen |
| Gruppen von |
| Eine Textnachricht an einen direkten Empfänger oder eine Gruppe senden |
| Desktop-DB / |
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.localist für lokale Geheimnisse wieSIGNAL_ACCOUNTgedacht 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-clistammen.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-clinicht gefunden — bestätigen Sie, dasssignal-cliimPATHist oder setzen SieSIGNAL_CLI_PATHin.env.local. Unter macOS istbrew install signal-clider einfachste Weg.Lesen/Suchen funktioniert, aber Senden schlägt fehl —
signal-cliist nicht verknüpft oderSIGNAL_ACCOUNTist nicht gesetzt. Führen Siesignal-cli listAccountszur Überprüfung aus und prüfen Sie dann.env.local.signal-cli linkhängt oder schlägt fehl — übergeben Sie bei aktuellen Versionen kein-a/--accountanlink. Führen Siesignal-cli link -n "signal-mcp"aus und scannen Sie den QR-Code von Ihrem Telefon.MCP-Client kann den Server nicht starten —
argsmuss einen absoluten Pfad zum Repository enthalten, nicht relativ. Wennuvselbst mitspawn uv ENOENTfehlschlägt, siehe macOS:uvPATH.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 pytesterfolgreich ist.
Siehe CLAUDE.md für den vollständigen Entwicklungsworkflow.
Lizenz
MIT-Lizenz – siehe 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.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP Server for retrieving Signal messages using signal-export logic.8-
- MIT
- 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-