mcp-signal
mcp-signal
Un servidor local del Protocolo de Contexto de Modelo (MCP) que lee el historial de Signal Desktop desde la base de datos cifrada local a través de
signal-exporty envía mensajes salientes mediantesignal-cli.
mcp-signal se centra en el flujo de trabajo principal para la automatización personal de Signal: listar chats, leer mensajes, buscar mensajes, inspeccionar grupos y enviar mensajes a chats directos o grupales. Todo se ejecuta localmente; transporte stdio sin oyente de red.
Aviso: backend mixto. La lectura/búsqueda proviene de la base de datos local de Signal Desktop. El envío utiliza
signal-cli, que debe instalarse y vincularse a una cuenta de Signal por separado. Sisignal-clino está disponible, la lectura/búsqueda sigue funcionando, pero las herramientas de envío no.
Características
Listar chats directos y grupales desde Signal Desktop
Leer mensajes recientes de un chat
Buscar mensajes dentro de un chat o en todos los chats
Listar chats grupales con IDs de grupo de
signal-clipara uso salienteEnviar un mensaje a:
un destinatario directo por número de teléfono
un grupo por ID de grupo
un chat por nombre exacto de chat (con comprobaciones de ambigüedad)
Se ejecuta completamente en su máquina; transporte stdio sin oyente de red
Related MCP server: Signal MCP
Configuración
Requisitos previos
Python 3.13+
Signal Desktop con una base de datos de mensajes local existente
signal-cliinstalado y vinculado si desea realizar envíos salientes
Instalación
Clonar este repositorio
git clone https://github.com/Sealjay/mcp-signal.git cd mcp-signalInstalar dependencias
uv syncInstalar
signal-cli(opcional: solo necesario para envíos salientes)En macOS, la ruta más sencilla es Homebrew:
brew install signal-cli
Configurar envíos salientes
El servidor carga automáticamente un archivo local .env.local desde la raíz del repositorio si está presente. Este archivo está ignorado por git y es el lugar recomendado para la configuración local de la máquina.
cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOFVariables de entorno opcionales:
Variable | Propósito |
| Sobrescribir la ruta del binario |
| Sobrescribir el directorio de datos de Signal Desktop |
| Contraseña para bases de datos de escritorio cifradas si es necesario |
| Clave sin procesar para bases de datos de escritorio cifradas si es necesario |
Las variables de entorno establecidas en el shell tienen prioridad sobre .env.local.
Vincular signal-cli (solo en la primera ejecución)
mcp-signal no gestiona la vinculación por sí mismo. Primero vincule el dispositivo signal-cli local:
signal-cli link -n "signal-mcp"Escanee el código QR en la aplicación móvil de Signal (Ajustes → Dispositivos vinculados → Vincular nuevo dispositivo).
No pase -a / --account a link en las versiones actuales de signal-cli: vincular un nuevo dispositivo secundario no requiere un número de teléfono allí.
Después de aceptar el QR, confirme que la cuenta vinculada sea visible:
signal-cli listAccountsEsa cuenta debe coincidir con el valor de SIGNAL_ACCOUNT en .env.local.
signal-cli almacena el estado de su cuenta vinculada en su propio directorio de datos local (normalmente ~/.local/share/signal-cli/data en macOS/Linux). Ese estado vive fuera de este repositorio y no es enviado por mcp-signal.
Verifique que todo esté conectado:
uv run signal-mcp smokeConfiguración del cliente MCP
Todos los clientes inician el servidor de la misma manera a través de stdio. En macOS, es posible que necesite la ruta absoluta a uv: consulte macOS: uv PATH a continuación.
Claude Code
La ruta más rápida es la CLI:
claude mcp add --transport stdio signal --scope user -- uv run --directory /absolute/path/to/mcp-signal signal-mcp serveAlternativamente, añádalo a .mcp.json en la raíz de su proyecto (o ~/.claude.json para un servidor con alcance de usuario):
{
"mcpServers": {
"signal": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
}
}
}Si edita el archivo directamente, reinicie la sesión de Claude Code para que los cambios surtan efecto.
Claude Desktop
Añada a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"signal": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
}
}
}Reinicie Claude Desktop. Debería ver signal listado como una integración disponible.
Cursor
Añada a ~/.cursor/mcp.json:
{
"mcpServers": {
"signal": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
}
}
}Reinicie Cursor.
macOS: uv PATH
Las aplicaciones GUI (Claude Desktop, Cursor) no siempre heredan el PATH de su terminal interactivo, por lo que uv puede fallar con spawn uv ENOENT. Soluciónelo utilizando la ruta absoluta a uv en command:
Homebrew —
/opt/homebrew/bin/uv(Apple Silicon) o/usr/local/bin/uv(Intel)Instalación manual — ejecute
which uven su terminal para encontrarla
Ejemplo:
{
"mcpServers": {
"signal": {
"command": "/opt/homebrew/bin/uv",
"args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
}
}
}Arquitectura
Componente | Descripción |
Servidor MCP | Python/FastMCP, transporte stdio |
Ruta de lectura |
|
Ruta de envío |
|
Estado | Sin caché separada; lee directamente de los datos de Signal Desktop |
Flujo de datos
El cliente MCP inicia
signal-mcp servea través de stdio.Las herramientas de lectura/búsqueda llaman a
signal-exportcontra la base de datos local de Signal Desktop.El listado de grupos y los envíos salientes llaman a
signal-cli -a ACCOUNT jsonRpc.Los resultados se devuelven como JSON estructurado.
Estructura del proyecto
mcp-signal/
src/mcp_signal/
config.py
main.py
reader.py
server.py
signal_cli.py
tests/
CLAUDE.md
LICENSE
README.md
SECURITY.mdHerramientas
Herramienta | Propósito |
| Listar chats directos y grupales desde Signal Desktop |
| Leer mensajes de un chat específico |
| Buscar mensajes dentro de un chat o en todos los chats |
| Listar grupos desde |
| Enviar un mensaje de texto a un destinatario directo o grupo |
| Mostrar el estado de la BD de escritorio / |
Privacidad y seguridad
Sin relé en la nube. Sin oyente de red. Todos los datos permanecen en su máquina.
La lectura/búsqueda utiliza solo sus datos locales de Signal Desktop.
Las operaciones de envío requieren una cuenta de
signal-cliconfigurada localmente..env.localestá destinado a secretos locales comoSIGNAL_ACCOUNTy no se envía al repositorio.El estado del dispositivo vinculado de
signal-clise almacena en su propio directorio de datos de aplicación local, fuera de este repositorio, y no se envía.
Consulte SECURITY.md para saber cómo informar vulnerabilidades.
Limitaciones
Riesgo de inyección de prompts: como ocurre con muchos servidores MCP, este está sujeto a la tripleta letal. Los mensajes entrantes maliciosos podrían intentar instruir a un agente para que exfiltre otros mensajes. Trate la superficie de la herramienta en consecuencia y revise las acciones salientes antes de aprobarlas.
Backend mixto: el historial de chat proviene de Signal Desktop, mientras que los envíos salientes provienen de
signal-cli.Sin archivos adjuntos: envío solo de texto.
Sin notificaciones en tiempo real: solo sondeo/lectura.
Cuenta única por instancia de MCP.
Los envíos a grupos necesitan
signal-cli: las lecturas de la BD local por sí solas no proporcionan suficiente información para enviar a grupos de forma segura.
Desarrollo
uv sync
uv run signal-mcp smoke
uv run pytest
uv run ruff check .Solución de problemas
signal-clino encontrado — confirme quesignal-cliestá en elPATHo establezcaSIGNAL_CLI_PATHen.env.local. En macOS,brew install signal-clies la ruta más sencilla.La lectura/búsqueda funciona pero los envíos fallan —
signal-clino está vinculado oSIGNAL_ACCOUNTno está configurado. Ejecutesignal-cli listAccountspara verificar, luego revise.env.local.signal-cli linkse bloquea o falla — no pase-a/--accountalinken las versiones actuales. Ejecutesignal-cli link -n "signal-mcp"y escanee el QR desde su teléfono.El cliente MCP no puede iniciar el servidor —
argsdebe contener una ruta absoluta al repositorio, no relativa. Siuvfalla conspawn uv ENOENT, consulte macOS:uvPATH.No se devuelven mensajes — confirme que Signal Desktop está instalado y tiene historial de mensajes. La ruta de lectura consulta la base de datos local de Signal Desktop directamente.
Contribución
Las contribuciones son bienvenidas mediante pull request. Por favor:
Ejecute
uv run ruff check .antes de enviar.Asegúrese de que
uv run pytestpase.
Consulte CLAUDE.md para conocer el flujo de trabajo de desarrollo completo.
Licencia
Licencia MIT — consulte 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.
1Hosted 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-
- AlicenseAqualityAmaintenanceThe most complete Signal MCP server and CLI.81279 PyPI12MIT
- 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-