linkwarden-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) para Linkwarden, el gestor de marcadores autoalojado que conserva una copia permanente de cada página que guarda.

Permite que un cliente MCP — Claude Code, Claude Desktop, Codex — busque en una colección de marcadores, la organice en colecciones y etiquetas, y lea el texto del artículo conservado de una página guardada, de modo que se pueda resumir o citar un enlace archivado sin tener que volver a obtener el sitio en vivo.

📖 Documentación completa en linkwarden-mcp.ni-c.de

Nota: La referencia de API publicada de Linkwarden está incompleta. Este servidor se escribió según las rutas en apps/web/pages/api/v1/** y los esquemas de petición en packages/lib/schemaValidation.ts de linkwarden/linkwarden, verificado contra v2.16.0 el 17/08/2026. Esos dos archivos son la fuente de verdad para todas las herramientas aquí presentes.

Requisitos

• Node.js ≥ 22

• Una instancia de Linkwarden en ejecución

• Un token de acceso, creado en Configuración → Tokens de acceso

Linkwarden no tiene ámbitos por token: un token tiene todos los permisos de la cuenta que lo creó. Crea una cuenta dedicada con acceso solo a las colecciones que este servidor debe ver, en lugar de entregarle un token de administrador.

Related MCP server: linkwarden-mcp

Configuración

Usa https://. Sobre HTTP plano el token viaja sin cifrar; el servidor muestra una advertencia a menos que el host sea local. Para un certificado autofirmado es preferible una CA interna adecuada en lugar de LINKWARDEN_INSECURE_TLS.

El token se elimina del entorno del proceso una vez leído, por lo que no es visible para procesos hijos ni en /proc/<pid>/environ.

Sin credenciales, el servidor igual se inicia y muestra sus herramientas, de modo que los registros e inspectores puedan examinarlo; cada llamada entonces falla con instrucciones de configuración en lugar de llegar a la API.

Instalación

Claude Code

claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp

Claude Desktop

{
  "mcpServers": {
    "linkwarden": {
      "command": "npx",
      "args": ["-y", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_URL": "https://links.example.net",
        "LINKWARDEN_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.linkwarden]
command = "npx"
args = ["-y", "linkwarden-mcp"]
env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }

Desde el código fuente

npm install && npm run build
LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js

Docker

docker build -t linkwarden-mcp .
docker run --rm -i \
  -e LINKWARDEN_URL=https://links.example.net \
  -e LINKWARDEN_TOKEN=… \
  linkwarden-mcp

Herramientas

Lectura

Escritura

No se registran en absoluto cuando LINKWARDEN_READ_ONLY=true. Las herramientas marcadas con 🔒 requieren un token de confirmación.

Deliberadamente no expuestas

• Gestión de tokens de acceso (/tokens). Una herramienta que puede emitir credenciales API es una superficie de escalada de privilegios, y un servidor de marcadores no tiene razón para tener una.

• Administración de usuarios (/users, eliminación de cuentas). Fuera del ámbito.

• Exportación e importación de copias de seguridad (/migration). La exportación vuelca toda la instancia en el contexto del modelo; la importación puede destruirla.

• Resaltados (highlights). Crear uno necesita desplazamientos exactos de caracteres dentro del documento preservado, que un modelo no puede producir de manera significativa, y Linkwarden no ofrece una ruta para listar resaltados existentes.

• Cargas de archivos y las URL firmadas de preserved, que necesitan que se configure NEXT_PUBLIC_USER_CONTENT_DOMAIN.

• La ruta obsoleta de listado GET /links — search_links usa GET /search en su lugar, que es lo que el propio Linkwarden recomienda.

Seguridad

• Las herramientas destructivas son de dos pasos. La primera llamada devuelve un token de confirmación de corta duración vinculado al objetivo exacto; solo una segunda llamada que lleve ese token realiza la operación. Un modelo no puede cumplir esta puerta por sí solo, y un token emitido para un enlace, conjunto de etiquetas o cambio no se puede reutilizar para otro.

• Ampliar la visibilidad se considera destructivo. Publicar una colección y cambiar la URL de un enlace —que elimina todas las copias preservadas de la página anterior— ambos necesitan una confirmación, no solo las eliminaciones.

• Las solicitudes de confirmación nunca citan contenido de Linkwarden. Los títulos, URLs, descripciones y nombres de colección provienen de páginas guardadas y de otros usuarios de la instancia; solo aparecen conteos e ids en el texto que el modelo lee.

• El contenido devuelto se marca como datos no confiables, en particular el texto del artículo preservado, que está escrito por quien controle el sitio de destino.

• Las actualizaciones parciales nunca borran campos. Las rutas de actualización de Linkwarden reemplazan todo el registro, así que este servidor lee el estado actual y fusiona; de lo contrario, una actualización eliminaría silenciosamente las etiquetas de un enlace o los colaboradores de una colección.

• Un 200 no se considera confiable por sí mismo. Varias rutas de Linkwarden reportan fallos con HTTP 200 y una frase de error en el cuerpo, y una ruta sin un manejador para el método usado responde 200 sin nada. Ambos se reportan como errores, no como una escritura exitosa.

• Los cuerpos de error se truncan, las páginas HTML de error se descartan por completo, las redirecciones nunca se siguen (para que el token de portador no se pueda reenviar a otro host), y cada solicitud tiene un tiempo de espera.

• LINKWARDEN_READ_ONLY=true no registra las herramientas de escritura en absoluto.

• Riesgo residual: dentro de los permisos del token que configures, un modelo al que se le pida hacer algo destructivo y que un usuario confirme, aún puede hacerlo. Limita la cuenta y mantén las solicitudes de permiso a nivel de host activadas.

Desarrollo

npm install
npm run build
npm test
npm run test:coverage
npm run lint
npm run format
npm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md se genera; CI falla si la copia confirmada ya no coincide con el código. El sitio de documentación vive en docs/ con su propio package.json y archivo de bloqueo — VitePress no debe terminar en la instalación raíz, que se ejecuta en la compilación Docker y en toda la matriz de pruebas.

Consulta CONTRIBUTING.md.

Publicación

Todo se maneja mediante una etiqueta (tag); no hay un paso de publicación manual.

1. Mueve la sección [Unreleased] de CHANGELOG.md a la nueva versión y fechala. El flujo de trabajo de lanzamiento extrae esa sección con awk, por lo que el formato del encabezado ## [x.y.z] es importante.

2. Aumenta la version en package.json.

3. npm run lint && npm run build && npm run test:coverage.

4. Haz commit, luego una etiqueta anotada firmada:

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1

release.yml entonces verifica que la etiqueta coincida con package.json, publica en npm mediante Trusted Publishing (OIDC — no existe token npm que pueda filtrarse) con procedencia, sincroniza la versión en ambas entradas del paquete server.json, publica en el registro MCP y crea el lanzamiento de GitHub a partir de la sección del changelog. ci.yml envía la imagen de contenedor multi-arquitectura a GHCR en paralelo.

Si el paso del registro falla, arréglalo en main y ejecuta el flujo de trabajo mcp-registry.yml a mano. Re-ejecutar el trabajo fallido no es una opción: este checkout de la etiqueta inmutable, por lo que una corrección en main nunca podría alcanzarlo.

Licencia

MIT © Willi Thiel