signal-mcp

Un servidor MCP de Node/TypeScript que lee directamente la base de datos SQLite cifrada de Signal Desktop y expone herramientas de consulta más completas que el signal-mcp-server original de Python.

Solo lectura. La base de datos se abre con readonly: true y query_only=ON. El servidor no puede modificar los datos de Signal.

Requisitos

• macOS, con Signal Desktop instalado y al menos una sesión iniciada.

• Node.js 20+.

• En la primera ejecución verás una solicitud del Llavero de macOS: apruébala (y marca Siempre permitir si no quieres que se te vuelva a preguntar). El servidor lee la contraseña de safeStorage de Signal desde tu llavero de inicio de sesión para descifrar la clave de SQLCipher.

Related MCP server: Cursor DB MCP Server

Instalación

Opción A: instalar desde GitHub (recomendado)

Se instala globalmente mediante npm. El script prepare del repositorio ejecuta tsc automáticamente para que no necesites una carpeta dist/ precompilada.

npm install -g git+https://github.com/jagypus/signal-mcp.git

Luego regístralo en Claude Code:

claude mcp add signal --scope user -- signal-mcp

Eso es todo. Abre Claude Code y prueba: "List my Signal chats." (Lista mis chats de Signal).

Para actualizar más tarde:

npm install -g git+https://github.com/jagypus/signal-mcp.git

Para eliminar:

claude mcp remove signal
npm uninstall -g signal-mcp

Opción B: clonar y compilar (para desarrollo)

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build
claude mcp add signal --scope user -- node "$(pwd)/dist/index.js"

Opción C: configuración manual

Si prefieres editar tu configuración de MCP directamente, añade esto a la configuración de servidores MCP de Claude Code (por ejemplo, el bloque mcpServers de ~/.claude.json, o un archivo de proyecto .mcp.json):

{
  "mcpServers": {
    "signal": {
      "command": "signal-mcp"
    }
  }
}

…o, para la ruta del repositorio clonado:

{
  "mcpServers": {
    "signal": {
      "command": "node",
      "args": ["/absolute/path/to/signal-mcp/dist/index.js"]
    }
  }
}

Verificar

claude mcp list

Deberías ver signal en la lista. Reinicia Claude Code si ya estaba ejecutándose, luego pídele que liste tus chats.

Herramientas

Todas las entradas se validan con Zod. Las marcas de tiempo son ISO 8601 de entrada/salida.

Reglas de filtrado

• exclude_system (por defecto true) mantiene solo type IN ('incoming','outgoing'), filtrando keychange, profile-change, group-v2-change, timer-notification, etc.

• only_with_body (por defecto true) excluye filas que solo contienen archivos adjuntos / reacciones / stickers donde body IS NULL.

• sender: me (saliente), them (entrante), any (ambos).

Desarrollo

git clone https://github.com/jagypus/signal-mcp.git
cd signal-mcp
npm install
npm run build               # compile to dist/
npm run dev                 # tsx, stdio (no build step)
npm run probe               # dump schema/FTS/types against the live DB
npx tsx scripts/smoke.ts    # exercise every tool against the live DB

Cómo abre la base de datos

Signal Desktop en macOS almacena la base de datos SQLCipher v4 en ~/Library/Application Support/Signal/sql/db.sqlite. Las versiones modernas de Signal almacenan la clave de SQLCipher cifrada en config.json bajo encryptedKey usando el safeStorage de Electron:

• Elimina el prefijo v10/v11 → texto cifrado AES-128-CBC.

• Clave de cifrado = PBKDF2-HMAC-SHA1(contraseña, "saltysalt", 1003 iteraciones, 16 bytes).

• En macOS, la contraseña se obtiene mediante security find-generic-password -s "Signal Safe Storage" -a "Signal" -w (una solicitud del llavero la primera vez).

• El IV es de 16 bytes de 0x20.

El texto plano es la clave SQLCipher hexadecimal de 64 caracteres. También se admiten compilaciones antiguas de Signal con una key en texto plano en config.json.

La base de datos se abre con better-sqlite3-multiple-ciphers en modo readonly: true y query_only=ON se establece como medida de seguridad adicional. Abrirla mientras Signal Desktop se está ejecutando funciona bien porque SQLCipher utiliza WAL.

Advertencia sobre la búsqueda

messages_fts existe pero utiliza el signal_tokenizer personalizado de Signal, que solo es registrado por el código nativo de Signal Desktop. Los lectores de terceros no pueden ejecutar consultas MATCH contra él, por lo que search_messages prueba una vez y recurre silenciosamente a body LIKE '%query%'.

Entorno

Notas multiplataforma

• macOS: gestionado.

• Linux: safeStorage v10 usa la contraseña literal peanuts. v11 (libsecret/KWallet) no está implementado: establece SIGNAL_KEY explícitamente.

• Windows: no implementado: establece SIGNAL_KEY explícitamente.

Estructura del proyecto

src/
  index.ts             # MCP server bootstrap
  db.ts                # connection + safeStorage key decryption
  schema.ts            # zod input shapes
  util/
    time.ts            # iso <-> ms
    messages.ts        # row shaping, display name resolution
    sql.ts             # shared filter SQL
  tools/
    listChats.ts
    getRecentMessages.ts
    getChatMessages.ts
    searchMessages.ts
    querySql.ts
scripts/
  probe.ts             # live-DB schema dump
  smoke.ts             # live-DB end-to-end check

Licencia

MIT — ver LICENSE.

Este proyecto no está afiliado ni respaldado por Signal Messenger LLC. Signal Desktop en sí tiene licencia AGPL-3.0; este proyecto no redistribuye ni modifica ningún código de Signal, solo lee la base de datos SQLite local que Signal Desktop crea en tu propia máquina.