Skip to main content
Glama
mcp-signal

mcp-signal

mcp-signal

Python uv MCP License: MIT GitHub issues GitHub stars Sealjay/mcp-signal MCP server

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-export y envía mensajes salientes mediante signal-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. Si signal-cli no 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-cli para uso saliente

  • Enviar 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+

  • uv

  • Signal Desktop con una base de datos de mensajes local existente

  • signal-cli instalado y vinculado si desea realizar envíos salientes

Instalación

  1. Clonar este repositorio

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

    uv sync
  3. Instalar 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"
EOF

Variables de entorno opcionales:

Variable

Propósito

SIGNAL_CLI_PATH

Sobrescribir la ruta del binario signal-cli

SIGNAL_DATA_DIR

Sobrescribir el directorio de datos de Signal Desktop

SIGNAL_DB_PASSWORD

Contraseña para bases de datos de escritorio cifradas si es necesario

SIGNAL_DB_KEY

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 listAccounts

Esa 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 smoke

Configuració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 serve

Alternativamente, 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 uv en 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

signal-export leyendo la base de datos local de Signal Desktop

Ruta de envío

signal-cli JSON-RPC lanzado bajo demanda

Estado

Sin caché separada; lee directamente de los datos de Signal Desktop

Flujo de datos

  1. El cliente MCP inicia signal-mcp serve a través de stdio.

  2. Las herramientas de lectura/búsqueda llaman a signal-export contra la base de datos local de Signal Desktop.

  3. El listado de grupos y los envíos salientes llaman a signal-cli -a ACCOUNT jsonRpc.

  4. 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.md

Herramientas

Herramienta

Propósito

list_chats

Listar chats directos y grupales desde Signal Desktop

read_messages

Leer mensajes de un chat específico

search_messages

Buscar mensajes dentro de un chat o en todos los chats

list_groups

Listar grupos desde signal-cli, incluyendo IDs de grupo

send_message

Enviar un mensaje de texto a un destinatario directo o grupo

get_status

Mostrar el estado de la BD de escritorio / signal-cli / cuenta

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-cli configurada localmente.

  • .env.local está destinado a secretos locales como SIGNAL_ACCOUNT y no se envía al repositorio.

  • El estado del dispositivo vinculado de signal-cli se 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-cli no encontrado — confirme que signal-cli está en el PATH o establezca SIGNAL_CLI_PATH en .env.local. En macOS, brew install signal-cli es la ruta más sencilla.

  • La lectura/búsqueda funciona pero los envíos fallan — signal-cli no está vinculado o SIGNAL_ACCOUNT no está configurado. Ejecute signal-cli listAccounts para verificar, luego revise .env.local.

  • signal-cli link se bloquea o falla — no pase -a / --account a link en las versiones actuales. Ejecute signal-cli link -n "signal-mcp" y escanee el QR desde su teléfono.

  • El cliente MCP no puede iniciar el servidor — args debe contener una ruta absoluta al repositorio, no relativa. Si uv falla con spawn uv ENOENT, consulte macOS: uv PATH.

  • 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 pytest pase.

Consulte CLAUDE.md para conocer el flujo de trabajo de desarrollo completo.

Licencia

Licencia MIT — consulte LICENSE.

Available Tools

9 tools
chat_activityChat ActivityA
Read-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 StatusA
Read-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 ChatsA
Read-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 GroupsA
Read-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 MessagesA
Read-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 MessagesA
Read-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

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Signal via signal-cli that enables sending and receiving messages, managing contacts and groups, and reacting over stdio.
      8 npm
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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
      -