PaperlessMCP

PaperlessMCP

Deja de organizar tus documentos manualmente. Deja que la IA lo haga.

Tienes una instancia de Paperless-ngx. Tienes cientos (¿miles?) de documentos. Sabes que deberías etiquetarlos, asignar corresponsales, organizarlos correctamente. ¿Pero quién tiene tiempo para eso?

PaperlessMCP conecta tu Paperless-ngx con cualquier IA compatible con MCP. Ahora, en lugar de hacer clic en la interfaz, solo preguntas:

"Encuentra todos mis documentos de impuestos de 2023"

"Etiqueta estas 50 facturas como 'Gasto de negocio' y asigna el corresponsal a 'Acme Corp'"

"Sube este recibo y averigua qué es"

"¿Qué documentos me faltan en mi carpeta de seguros?"

Es Paperless-ngx con esteroides de LLM. Una interfaz diseñada específicamente para que la IA gestione tus documentos mientras tú haces literalmente cualquier otra cosa.

---

¿Qué Puede Hacer la IA con tu Paperless?

Todo. CRUD completo en cada tipo de entidad:

Tú Dices	La IA Hace
"Encuentra recibos de Amazon por más de $100"	Busca documentos con filtros
"Etiqueta todas las facturas de 2024 como 'Año Fiscal 2024'"	Actualiza en masa docenas de documentos a la vez
"Sube este PDF y archívalo adecuadamente"	Sube, auto-etiqueta, asigna corresponsal
"Elimina todos los documentos etiquetados como 'Basura'"	Elimina con confirmación (prueba en seco por defecto)
"Crea una etiqueta para registros médicos, hazla roja"	Crea etiqueta con color
"¿Quién me envía más documentos?"	Lista corresponsales por número de documentos
"Configura una ruta de almacenamiento para documentos legales"	Crea estructura de carpetas organizada

43 herramientas que cubren:

• Documentos — búsqueda, subida, descarga, actualización, eliminación, operaciones masivas, reprocesamiento OCR
• Etiquetas — CRUD completo con colores, reglas de coincidencia y padres jerárquicos
• Corresponsales — rastrea quién te envía cosas
• Tipos de Documento — clasifica facturas, recibos, contratos, lo que sea
• Rutas de Almacenamiento — organiza archivos con plantillas inteligentes
• Campos Personalizados — añade tus propios metadatos (fechas, cantidades, URLs, etc.)

Todas las operaciones destructivas requieren confirmación explícita. Las operaciones masivas usan por defecto el modo de prueba en seco, para que la IA no pueda destruir tu archivo por accidente.

---

¿Es PaperlessMCP Adecuado para Ti?

Sí, si:

• Ejecutas Paperless-ngx (autoalojado o en la nube)
• Usas cualquier asistente de IA que hable MCP (Claude, o cualquier otra cosa que soporte el protocolo)
• Tienes un atraso de documentos sin etiquetar y te sientes culpable por ello
• Prefieres decir "organiza esto" en lugar de hacer clic en 47 botones
• Quieres consultar tus documentos en lenguaje natural
• Piensas que las computadoras deberían trabajar para ti, no al revés

No, si:

• No usas Paperless-ngx (esta no es una herramienta general de documentos)
• Disfrutas etiquetando documentos manualmente (raro, pero respeto)
• No confías en la IA con tus archivos (justo; las operaciones destructivas requieren confirmación, y las operaciones masivas usan por defecto el modo de prueba en seco)

El punto ideal: Tienes Paperless funcionando, tienes una IA compatible con MCP y quieres que sean amigos.

---

Primeros Pasos

Necesitarás

1. Una instancia de Paperless-ngx con un token de API (Configuración → Django Admin → Tokens → Crea uno para tu usuario)

2. Una IA compatible con MCP (Claude Desktop, o cualquier cosa que hable el protocolo)

Opción 1: Docker (Recomendado)

El camino más rápido de cero a hablar con tus documentos.

docker run -d \
  --name paperless-mcp \
  --restart unless-stopped \
  -e PAPERLESS_BASE_URL=https://your-paperless.example.com \
  -e PAPERLESS_API_TOKEN=your-token-here \
  -p 5000:5000 \
  -v paperless-outbox:/home/mcp/outbox \
  ghcr.io/barryw/paperlessmcp:vX.Y.Z

Toma la versión de la insignia de arriba. El pipeline de lanzamiento también publica latest, pero fijar una etiqueta con versión te da un despliegue reproducible.

Conecta tu cliente MCP a http://localhost:5000/mcp y empieza a hablar con tus documentos.

El volumen paperless-outbox es donde paperless_documents_export_to_outbox escribe los archivos exportados. Sin él, las exportaciones permanecen dentro del contenedor y ningún otro proceso puede acceder a ellas — consulta Compartir la bandeja de salida con otro servidor MCP.

Opción 2: Claude Desktop

Añade a tu archivo de configuración:

SO	Ruta
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paperless": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/PaperlessMCP/PaperlessMCP", "--", "--stdio"],
      "env": {
        "PAPERLESS_BASE_URL": "https://your-paperless.example.com",
        "PAPERLESS_API_TOKEN": "your-token-here"
      }
    }
  }
}

Reinicia Claude Desktop. Busca el icono de herramientas — Paperless debería estar ahí.

Opción 3: Claude Code

Un solo comando si ya estás ejecutando el servidor en algún lugar:

# Connect to a running Streamable HTTP server
claude mcp add --transport http paperless http://localhost:5000/mcp

O ejecuta desde el código fuente con stdio:

claude mcp add --transport stdio paperless \
  -e PAPERLESS_BASE_URL=https://your-paperless.example.com \
  -e PAPERLESS_API_TOKEN=your-token-here \
  -- dotnet run --project /path/to/PaperlessMCP/PaperlessMCP -- --stdio

Verifica que está ahí:

claude mcp list

Opción 4: Proxy LiteLLM

LiteLLM puede registrar PaperlessMCP como un servidor MCP HTTP transmisible en config.yaml.

Inicia PaperlessMCP primero usando Docker, Kubernetes o el código fuente, luego añádelo a LiteLLM:

mcp_servers:
  paperless:
    url: "http://paperless-mcp:5000/mcp"
    transport: "http"
    description: "Paperless-ngx document management"

Usa una URL que el proceso de LiteLLM pueda alcanzar. En Docker Compose, establece el host al nombre del servicio PaperlessMCP de ese archivo Compose, como paperless-mcp. Si LiteLLM se ejecuta directamente en el host y PaperlessMCP publica el puerto 5000, usa http://127.0.0.1:5000/mcp.

Establece transport: "http" explícitamente para el endpoint /mcp de PaperlessMCP. La configuración MCP de LiteLLM usa por defecto sse, que es el transporte incorrecto para este endpoint.

PAPERLESS_API_TOKEN pertenece al servicio PaperlessMCP; es el token que PaperlessMCP usa al llamar a Paperless-ngx. PaperlessMCP no requiere un token entrante en /mcp a menos que pongas una capa de autenticación separada, como un proxy inverso, delante de él.

Para el almacenamiento MCP respaldado por base de datos de LiteLLM, habilita el almacenamiento en base de datos en LiteLLM:

general_settings:
  store_model_in_db: true

Para configuración estática, mantén el servidor bajo la clave de nivel superior mcp_servers.

Opción 5: Kubernetes

Para los que ejecutan k8s en su homelab. Incluimos manifiestos listos para usar con soporte de Kustomize.

# Clone and customize
git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP/k8s

# Customize the checked-in manifests:
# - Set PAPERLESS_BASE_URL in secret.yaml.
# - Pin a versioned image tag in deployment.yaml.
# - The image is public, so remove imagePullSecrets unless your cluster
#   provides the referenced ghcr-secret.

# Create the API token secret (it is not managed by kustomization.yaml)
kubectl create secret generic paperless-token \
  --from-literal=token=your-api-token-here

# Deploy
kubectl apply -k .

Ver los manifiestos

Incluye: Deployment, Service, Ingress, Secret de URL base y Kustomization. Ajusta a tu gusto.

Opción 6: Desde el Código Fuente

Para contribuyentes y curiosos:

git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP
dotnet run --project PaperlessMCP             # Streamable HTTP on :5000
dotnet run --project PaperlessMCP -- --stdio  # stdio mode

Requiere .NET 10 SDK.

---

El Juego de Herramientas Completo

43 herramientas, organizadas por lo que tocan. Cada entidad soporta CRUD completo.

Documentos — el evento principal

Herramienta	Qué hace
paperless_documents_search	Encuentra documentos con búsqueda de texto completo y filtros
paperless_documents_get	Obtén un documento por ID con todos los metadatos
paperless_documents_upload	Sube un documento (base64)
paperless_documents_upload_from_path	Sube desde una ruta de archivo
paperless_documents_update	Actualiza título, etiquetas, corresponsal, etc.
paperless_documents_delete	Elimina un documento (requiere confirmación)
paperless_documents_bulk_update	Actualiza múltiples documentos a la vez
paperless_documents_download	Obtén URLs de descarga, vista previa y miniatura; opcionalmente incluye archivos pequeños como base64
paperless_documents_export_to_outbox	Escribe el archivo de un documento en el directorio de bandeja de salida compartido para que otra herramienta pueda adjuntarlo por ruta
paperless_documents_preview	Obtén URL de vista previa
paperless_documents_thumbnail	Obtén URL de miniatura
paperless_documents_reprocess	Vuelve a ejecutar OCR en un documento

Etiquetas — organiza todo

Herramienta	Qué hace
paperless_tags_list	Lista todas las etiquetas
paperless_tags_get	Obtén una etiqueta por ID
paperless_tags_create	Crea una etiqueta con color opcional, reglas de coincidencia y padre
paperless_tags_update	Actualiza una etiqueta, incluyendo cambiar o limpiar su padre
paperless_tags_delete	Elimina una etiqueta
paperless_tags_bulk_delete	Elimina múltiples etiquetas

Corresponsales — quién te envía cosas

Herramienta	Qué hace
paperless_correspondents_list	Lista todos los corresponsales
paperless_correspondents_get	Obtén un corresponsal por ID
paperless_correspondents_create	Crea con reglas de coincidencia opcionales
paperless_correspondents_update	Actualiza un corresponsal
paperless_correspondents_delete	Elimina un corresponsal
paperless_correspondents_bulk_delete	Elimina múltiples corresponsales

Tipos de Documento — facturas, recibos, contratos...

Herramienta	Qué hace
paperless_document_types_list	Lista todos los tipos de documento
paperless_document_types_get	Obtén un tipo de documento por ID
paperless_document_types_create	Crea con reglas de coincidencia opcionales
paperless_document_types_update	Actualiza un tipo de documento
paperless_document_types_delete	Elimina un tipo de documento
paperless_document_types_bulk_delete	Elimina múltiples tipos de documento

Rutas de Almacenamiento — dónde viven las cosas

Herramienta	Qué hace
paperless_storage_paths_list	Lista todas las rutas de almacenamiento
paperless_storage_paths_get	Obtén una ruta de almacenamiento por ID
paperless_storage_paths_create	Crea con plantilla de ruta
paperless_storage_paths_update	Actualiza una ruta de almacenamiento
paperless_storage_paths_delete	Elimina una ruta de almacenamiento
paperless_storage_paths_bulk_delete	Elimina múltiples rutas de almacenamiento

Campos Personalizados — tus propios metadatos

Herramienta	Qué hace
paperless_custom_fields_list	Lista todas las definiciones de campos personalizados
paperless_custom_fields_get	Obtén un campo personalizado por ID
paperless_custom_fields_create	Crea un campo (cadena, fecha, número, monetario, etc.)
paperless_custom_fields_update	Actualiza una definición de campo
paperless_custom_fields_delete	Elimina un campo
paperless_custom_fields_assign	Asigna un valor de campo a un documento

Salud — ¿está vivo?

Herramienta	Qué hace
paperless_ping	Comprueba conectividad y autenticación
paperless_capabilities	Lista las características soportadas

---

Configuración

Variables de entorno. Eso es todo. No hay archivos de configuración que gestionar.

Variable	Requerida	Predeterminado	Descripción
PAPERLESS_BASE_URL	Sí	—	Tu URL de Paperless-ngx
PAPERLESS_API_TOKEN	Sí	—	Token de API para autenticación
MCP_PORT		5000	Puerto para el modo HTTP transmisible
MCP_RELAX_ACCEPT_HEADER		false	Normaliza los encabezados /mcp POST Accept para clientes que no pueden enviar ambos tipos de medios HTTP transmisibles
MAX_PAGE_SIZE		100	Límite superior para solicitudes paginadas a Paperless-ngx realizadas por este servidor
HTTP_TIMEOUT_SECONDS		30	Tiempo de espera para solicitudes a Paperless-ngx. Auméntalo si las búsquedas grandes de texto completo agotan el tiempo
PAPERLESS_OUTBOX_DIR		/home/mcp/outbox	Directorio en el que escribe paperless_documents_export_to_outbox. Móntalo como un volumen compartido o las exportaciones serán inaccesibles fuera del contenedor

Alias soportados: PAPERLESS_URL y PAPERLESS_TOKEN también funcionan si ese es tu estilo, y OUTBOX_DIR se acepta para PAPERLESS_OUTBOX_DIR.

Compartir la bandeja de salida con otro servidor MCP

paperless_documents_export_to_outbox descarga un documento en el servidor y lo escribe en PAPERLESS_OUTBOX_DIR, devolviendo {path, filename, mime_type, size_bytes}. La idea es que los bytes nunca viajan a través del contexto del modelo: otra herramienta (por ejemplo, un servidor de correo que adjunta archivos por ruta) lee el archivo directamente.

Eso solo funciona si ambos contenedores ven el mismo directorio. Monta un volumen en ambos y asegúrate de que la ruta que se le dice al otro servidor que lea coincida con la ruta que ve:

services:
  paperless-mcp:
    image: ghcr.io/barryw/paperlessmcp:vX.Y.Z
    environment:
      PAPERLESS_BASE_URL: https://your-paperless.example.com
      PAPERLESS_API_TOKEN: your-token-here
      PAPERLESS_OUTBOX_DIR: /home/mcp/outbox
    ports:
      - "5000:5000"
    volumes:
      - outbox:/home/mcp/outbox

  some-other-mcp:
    image: example/other-mcp:latest
    volumes:
      - outbox:/home/mcp/outbox

volumes:
  outbox:

Dos cosas que debes saber antes de confiar en ello:

• Los nombres llevan el id del documento. Un nombre derivado inserta el id antes de la extensión (invoice.pdf se convierte en invoice_42.pdf), de modo que dos documentos cuyo archivo tenga el mismo nombre no pueden sobrescribirse entre sí. Reexportar el mismo documento reemplaza su propio archivo. Un filename que pases tú mismo se usa tal cual, por lo que exportaciones repetidas bajo un mismo nombre sí se reemplazan entre sí.
• La versión archivada se nombra como tal. Con original=false (el valor predeterminado) Paperless sirve el PDF archivado, por lo que la exportación se nombra según el archivo archivado en lugar de según un original .jpg o .docx. Pasa original=true para obtener el archivo subido con su propio nombre.
• Las exportaciones aparecen completas. La descarga se transmite a un archivo temporal en la bandeja de salida y se renombra en su lugar, de modo que un lector al otro lado del volumen nunca recoge un archivo a medio escribir, y un enlace simbólico colocado en el destino se reemplaza en lugar de escribirse a través de él.
• El directorio debe ser escribible por el usuario del contenedor. La imagen se ejecuta como root a menos que lo anules, por lo que las exportaciones caen en un montaje bind propiedad de root — si el contenedor consumidor se ejecuta como un usuario no root, establece PAPERLESS_OUTBOX_DIR a un directorio que ambos puedan escribir, o arregla la propiedad tú mismo. El directorio se crea en la primera exportación, y un fallo aparece allí en lugar de al inicio.

Compatibilidad con LocalAI

Se espera que los clientes HTTP transmitibles envíen Accept: application/json, text/event-stream en las solicitudes POST /mcp. Algunos clientes no pueden configurar ese encabezado. Establece MCP_RELAX_ACCEPT_HEADER=true para que PaperlessMCP normalice los encabezados Accept faltantes o incompletos antes de que el SDK de MCP maneje la solicitud.

---

Apoya el Proyecto

Si PaperlessMCP te ahorra tiempo, considera apoyar el desarrollo:

Cada granito de arena ayuda a mantener las luces encendidas y los commits fluyendo.

---

Contribuciones

Sí, por favor. Usamos desarrollo basado en tronco con commits convencionales.

git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP
dotnet build
dotnet test

Las reglas:

• Commits convencionales (feat:, fix:, docs:, etc.) — las versiones aumentan automáticamente
• Las pruebas pasan o no se fusiona
• Las operaciones destructivas necesitan confirm=true; las operaciones masivas por defecto son en seco (dry-run)

Consulta CONTRIBUTING.md para obtener la información completa.

---

Licencia

MIT — haz lo que quieras, solo no me culpes.

---

Agradecimientos

• Paperless-ngx — el sistema de documentos que hace que valga la pena construir esto
• Model Context Protocol — el pegamento entre la IA y todo lo demás
• Todos los que alguna vez se han sentido culpables por sus documentos sin etiquetar