mcp-paperless-ngx

Construido contra la API REST versión 10, con tres cosas que hace de forma diferente:

• Cobertura justificada. Cada uno de los 92 endpoints documentados está expuesto como herramienta o aparece en src/tools/coverage.ts con una razón escrita para excluirlo. Una prueba lo verifica, de modo que una versión de Paperless que añada un endpoint haga fallar la CI en lugar de quedar silenciosamente sin soporte.

• Disciplina de tokens. Un documento de Paperless lleva su texto OCR completo. Los envoltorios ingenuos lo devuelven por defecto y una sola búsqueda puede agotar el contexto del modelo. Aquí, los resultados de las listas se recortan en el servidor mediante ?fields=, el texto vive detrás de su propia herramienta paginada, y ningún endpoint de lista pasa la respuesta cruda de la API — una prueba lo verifica. Véase Coste de contexto.

• Superficie limitada. 99 herramientas ahogarían la lista de herramientas de un modelo. Los conjuntos de herramientas permiten exponer solo lo que un cliente concreto necesita, y --read-only elimina por completo cualquier vía de escritura.

Paperless-ngx 2.x no es compatible: la versión 10 de la API introdujo endpoints (etiquetas anidadas, versiones de documentos, share_link_bundles, las operaciones de división de PDF) que este servidor asume que existen.

Inicio rápido

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=your-api-token \
  -- npx -y mcp-paperless-ngx

Claude Desktop, Cursor, Cline y otros clientes MCP

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your-api-token"
      }
    }
  }
}

Obtener un token de API

Interfaz web de Paperless → tu nombre de usuario (arriba a la derecha) → Mi perfil → el botón de flecha circular junto al campo del token de API.

Related MCP server: paperlessngx-mcp

Configuración

Los indicadores de línea de comandos --url, --token, --public-url, --toolsets y --read-only anulan el entorno. --check verifica la conectividad, --list-tools imprime las herramientas habilitadas.

Conjuntos de herramientas

mail y admin están desactivados por defecto porque la mayoría de las sesiones nunca los necesitan y cada herramienta extra cuesta contexto en cada petición. Actívalos explícitamente:

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

Coste de contexto

Envolver una API para un modelo de lenguaje tiene un coste que la propia API no tiene: todo lo que el modelo ve se paga en cada petición. Dos lugares donde eso afecta, y qué hace este servidor al respecto.

Respuestas. Tres formas son caras en Paperless y fáciles de devolver por accidente:

Definiciones de herramientas. Son el coste más grande y menos evidente: nombres, descripciones y esquemas JSON viajan con cada petición, se llame o no a alguna herramienta.

No hay forma de que eso sea gratis — es el precio de una herramienta que el modelo puede usar sin adivinar. Pero merece la pena ser deliberado: si tus sesiones solo buscan y archivan documentos, ejecutar PAPERLESS_TOOLSETS=documents,metadata ahorra más contexto que cualquier recorte de respuestas.

Seguridad

El servidor expone operaciones destructivas, porque un gestor de documentos sin ellas no es gran cosa. No intenta adivinar cuándo son apropiadas — ese juicio pertenece al cliente y al usuario. Lo que sí hace:

• Las herramientas destructivas están anotadas con destructiveHint: true, para que los clientes MCP puedan exigir confirmación.

• Las descripciones de las herramientas indican claramente lo que no se puede deshacer (empty_trash, delete_custom_field, delete_originals) y piden confirmación antes de la llamada.

• --read-only elimina toda herramienta de escritura de la lista, en lugar de rechazarlas en el momento de la llamada.

• Los endpoints masivos admiten un modo "aplicar a todo lo que coincida con este filtro". Este servidor no lo expone: las herramientas masivas aceptan listas explícitas de IDs, de modo que un filtro erróneo no pueda afectar silenciosamente a todo el archivo.

• create_share_link produce una URL accesible públicamente. Su descripción lo indica, y el prompt audit_sharing existe para revisar lo que ya está expuesto.

Los endpoints relacionados con credenciales (generación de tokens, registro de TOTP, desactivación del segundo factor de alguien) se excluyen deliberadamente. Véase EXCLUDED_ENDPOINTS para la lista completa y el razonamiento.

Prompts

Registrados como comandos de barra en los clientes que admiten prompts MCP:

Pruebas

Tres capas, porque detectan cosas diferentes:

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test comprueba el razonamiento propio de este servidor: cobertura de endpoints, valores de enumeración contra el esquema, que ninguna herramienta de listas filtre objetos crudos de la API, que el modo de solo lectura elimine realmente las escrituras.

smoke-test.mjs comprueba las suposiciones que hace sobre Paperless. Llama a todas las herramientas de solo lectura contra una instancia real, resolviendo los IDs a partir de llamadas de listas en lugar de codificarlos, e imprime los tamaños de las respuestas para que las herramientas caras sigan siendo visibles. No escribe nada.

write-test.mjs cubre el resto: subida y consumo, actualización de cada tipo de campo, notas, ediciones masivas de etiquetas, enlaces de compartición, rotación y un ciclo de ida y vuelta con la papelera.

Solo toca los objetos que crea él mismo. Todo lo que crea lleva el prefijo zz-mcp-test y se elimina de nuevo al final, y nunca modifica un documento que no haya subido. Si una ejecución se interrumpe, los restos con ese prefijo son seguros de eliminar. Prefiere una instancia de prueba si tienes una.

Mantenerse al día con Paperless

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs regenera schema/endpoints.json a partir del documento OpenAPI de tu propia instancia. El conjunto de pruebas informa entonces de cualquier endpoint que no esté ni expuesto ni excluido explícitamente. Ese es todo el bucle de mantenimiento: apúntalo a una versión más reciente de Paperless y la prueba te dirá qué ha cambiado.

Desarrollo

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

Trabajo previo

Ya existen varios servidores MCP para Paperless, sobre todo cubinet-code/paperless-ngx-mcp, y también nloui/paperless-mcp y barryw/PaperlessMCP. Están dirigidos a la API 2.x. Si usas Paperless-ngx 2.x, usa uno de esos; este asume 3.x.

Licencia

MIT. Ver LICENSE.