Servidor MCP de BookStack

Un servidor del Protocolo de Contexto de Modelo (MCP) que brinda a los asistentes de IA acceso completo a su documentación de BookStack: buscar, leer, crear y gestionar contenido.

npx bookstack-mcp

Características

• 20 herramientas de solo lectura + 18 herramientas de escritura para una cobertura completa de la API de BookStack

• Libros, capítulos, páginas, estantes, archivos adjuntos y comentarios: CRUD completo

• Soporte para papelera de reciclaje: restaure o elimine permanentemente contenido eliminado de forma lógica

• Validación de entrada con seguridad de tipos mediante Zod (coacciona automáticamente parámetros de cadena/número para una amplia compatibilidad con clientes)

• URLs incrustadas y vistas previas de contenido en todas las respuestas

• Alternativa de exportación a Markdown para páginas creadas en HTML, para que los clientes de IA siempre obtengan contenido utilizable

• Operaciones de escritura deshabilitadas por defecto por seguridad

• Funciona con Claude Desktop, Claude Code, LibreChat y cualquier cliente compatible con MCP

• Transportes Stdio y HTTP transmitible

Related MCP server: PDF RAG MCP Server

Inicio rápido

Instalar desde npm

npx bookstack-mcp

O clonar y compilar

git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
npm install && npm run build
npm start

Variables de entorno

BOOKSTACK_BASE_URL=https://your-bookstack.com   # Required
BOOKSTACK_TOKEN_ID=your-token-id                # Required
BOOKSTACK_TOKEN_SECRET=your-token-secret        # Required
BOOKSTACK_ENABLE_WRITE=false                    # Optional, default false
BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false        # Optional, default false

Advertencia de seguridad: BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=true deshabilita la verificación de certificados TLS para las solicitudes salientes a BookStack. Úselo solo para certificados autofirmados en una red local de confianza; las conexiones se vuelven vulnerables a ataques MITM. El servidor registra una línea de WARNING al inicio siempre que esto esté habilitado.

Configuración del cliente

Claude Desktop

Agréguelo a su configuración de Claude Desktop:

{
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

LibreChat (stdio, usuario único)

Agréguelo a su librechat.yaml:

mcpServers:
  bookstack:
    command: npx
    args:
      - -y
      - bookstack-mcp
    env:
      BOOKSTACK_BASE_URL: "https://your-bookstack.com"
      BOOKSTACK_TOKEN_ID: "your-token-id"
      BOOKSTACK_TOKEN_SECRET: "your-token-secret"

LibreChat (HTTP transmitible, recomendado para producción / Docker)

Ejecute el servidor como un servicio HTTP de larga duración y apunte LibreChat a la URL. Esta es la configuración correcta para implementaciones multiusuario o en contenedores.

Inicie el servidor en modo HTTP:

MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
BOOKSTACK_BASE_URL=https://your-bookstack.com \
BOOKSTACK_TOKEN_ID=your-token-id \
BOOKSTACK_TOKEN_SECRET=your-token-secret \
npx bookstack-mcp

Luego configure LibreChat:

mcpServers:
  bookstack:
    type: streamable-http
    url: http://bookstack-mcp:8080/mcp

Cambio importante en la versión 3.0.0: se ha eliminado el transporte obsoleto HTTP+SSE (GET /sse + POST /messages). El HTTP transmitible en /mcp ya utiliza SSE para respuestas en streaming y es el único transporte HTTP en los clientes MCP actuales. Si utiliza un cliente antiguo que necesita los endpoints heredados, fije la versión a bookstack-mcp@2.x.

Variables de entorno de transporte HTTP

Al enlazar a 0.0.0.0 (por ejemplo, dentro de un contenedor accesible desde otros servicios), establezca MCP_HTTP_ALLOWED_HOSTS con los nombres de host que LibreChat utilizará para llegar a este servidor, p. ej. MCP_HTTP_ALLOWED_HOSTS=bookstack-mcp,bookstack-mcp.internal.

Reinicie LibreChat después de realizar cambios en la configuración.

Claude Code (CLI)

La ruta recomendada es el mercado ttpears/claude-plugins, que incluye el manifiesto del plugin de este repositorio (.claude-plugin/plugin.json):

/plugin marketplace add ttpears/claude-plugins
/plugin install bookstack-mcp@ttpears-plugins

Luego, establezca las variables de entorno BOOKSTACK_* en su shell para que el servidor MCP del plugin pueda autenticarse:

export BOOKSTACK_BASE_URL=https://your-bookstack.com
export BOOKSTACK_TOKEN_ID=your-token-id
export BOOKSTACK_TOKEN_SECRET=your-token-secret

Instalación manual (alternativa)

Si prefiere no usar el mercado, registre el servidor directamente con claude mcp add. Repita --env para cada variable, coloque todas las banderas antes del nombre del servidor y use -- para marcar el inicio del comando que Claude Code ejecutará:

claude mcp add bookstack \
  --transport stdio \
  --scope user \
  --env BOOKSTACK_BASE_URL=https://your-bookstack.com \
  --env BOOKSTACK_TOKEN_ID=your-token-id \
  --env BOOKSTACK_TOKEN_SECRET=your-token-secret \
  -- npx -y bookstack-mcp

El ámbito (scope) elige dónde se escribe la entrada:

La entrada de configuración resultante se ve así (en .mcp.json para el ámbito de proyecto, o ~/.claude.json en caso contrario):

{
  "mcpServers": {
    "bookstack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Consejo para .mcp.json confirmado: Claude Code expande las referencias ${VAR} y ${VAR:-default} en .mcp.json desde el shell circundante. Úselo para mantener los secretos fuera de git: establezca "BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}" en el archivo y haga que cada desarrollador exporte la variable en su shell.

Recursos MCP

Los libros y las páginas también se exponen como recursos MCP, por lo que los clientes que exploran recursos (Claude Desktop, MCP Inspector, etc.) pueden mencionarlos directamente con @:

Ambas plantillas admiten autocompletado de id: a medida que escribe, el servidor busca en BookStack y devuelve los IDs coincidentes para que no tenga que recordar los IDs numéricos manualmente.

Herramientas disponibles

Operaciones de lectura (siempre disponibles)

Operaciones de escritura (requiere BOOKSTACK_ENABLE_WRITE=true)

Configuración de la API de BookStack

1. Inicie sesión en BookStack como administrador

2. Vaya a Configuración > Usuarios > Editar su usuario

3. Asegúrese de que el usuario tenga el permiso Acceder a la API del sistema

4. En la sección Tokens de API, cree un nuevo token

5. Copie el ID del token y el secreto del token

Seguridad

• Las operaciones de escritura están deshabilitadas por defecto

• Utilice HTTPS para instancias de producción

• Almacene los tokens de API de forma segura (nunca los confirme en git)

• Considere un usuario de BookStack dedicado con permisos limitados

Desarrollo

npm run dev          # Hot reload with tsx
npm run type-check   # Type checking only
npm run build        # Production build

Licencia

MIT