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

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:

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

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

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.