Servidor MCP Paperless-NGX

Un servidor MCP (Protocolo de Contexto de Modelo) para interactuar con un servidor API de Paperless-NGX. Este servidor proporciona herramientas para gestionar documentos, etiquetas, corresponsales y tipos de documentos en su instancia de Paperless-NGX.

Inicio rápido

Instalación mediante herrería

Para instalar Paperless NGX MCP Server para Claude Desktop automáticamente a través de Smithery :

Instalación manual

1. Instalar el servidor MCP:

2. Agreguelo a la configuración MCP de su Claude:

Para la extensión de VSCode, edite ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json :

Para la aplicación de escritorio Claude, edite ~/Library/Application Support/Claude/claude_desktop_config.json :

3. Obtenga su token API:
   1. Inicie sesión en su instancia Paperless-NGX
   2. Haga clic en su nombre de usuario en la parte superior derecha
   3. Seleccione "Mi perfil"
   4. Haga clic en el botón de flecha circular para generar un nuevo token
4. Reemplace los marcadores de posición en su configuración de MCP:
   • http://your-paperless-instance:8000 con su URL Paperless-NGX
   • your-api-token con el token que acaba de generar

¡Listo! Ahora puedes pedirle a Claude que te ayude a gestionar tus documentos de Paperless-NGX.

Ejemplo de uso

Aquí hay algunas cosas que puedes pedirle a Claude que haga:

• "Muéstrame todos los documentos etiquetados como 'Factura'"
• Buscar documentos que contengan 'declaración de impuestos'
• Crea una nueva etiqueta llamada "Recibos" con el color #FF0000.
• Descargar documento n.° 123
• "Enumerar todos los corresponsales"
• "Crear un nuevo tipo de documento llamado 'Extracto bancario'"

Herramientas disponibles

Operaciones de documentos

lista_documentos

Obtenga una lista paginada de todos los documentos.

Parámetros:

• página (opcional): Número de página
• page_size (opcional): Número de documentos por página

obtener_documento

Obtenga un documento específico por identificación.

Parámetros:

• id: ID del documento

buscar_documentos

Búsqueda de texto completo en documentos.

Parámetros:

• consulta: cadena de consulta de búsqueda

descargar_documento

Descargar un archivo de documento por ID.

Parámetros:

• id: ID del documento
• original (opcional): si es verdadero, descarga el archivo original en lugar de la versión archivada

edición masiva de documentos

Realizar operaciones masivas en múltiples documentos.

Parámetros:

• documentos: Matriz de ID de documentos
• método: Uno de:
  • set_correspondent: Establecer corresponsal para los documentos
  • set_document_type: Establece el tipo de documento para los documentos
  • set_storage_path: Establecer la ruta de almacenamiento para los documentos
  • add_tag: Agregar una etiqueta a los documentos
  • remove_tag: Eliminar una etiqueta de los documentos
  • modificar_etiquetas: Agregar y/o eliminar múltiples etiquetas
  • eliminar: Eliminar documentos
  • reprocesar: Reprocesar documentos
  • set_permissions: Establecer permisos de documentos
  • fusionar: fusionar varios documentos
  • dividir: dividir un documento en varios documentos
  • rotar: rotar páginas del documento
  • delete_pages: Eliminar páginas específicas de un documento
• Parámetros adicionales según el método:
  • corresponsal: ID para set_correspondent
  • document_type: ID para el conjunto_document_type
  • storage_path: ID para set_storage_path
  • etiqueta: ID para agregar/eliminar etiqueta
  • add_tags: Matriz de identificaciones de etiquetas para modificar_etiquetas
  • remove_tags: Matriz de identificaciones de etiquetas para modification_tags
  • permisos: Objeto para set_permissions con propietario, permisos, bandera de combinación
  • metadata_document_id: ID para la fusión para especificar la fuente de metadatos
  • delete_originals: Booleano para fusionar/dividir
  • páginas: Cadena para dividir "[1,2-3,4,5-7]" o eliminar_páginas "[2,3,4]"
  • grados: Número para rotar (90, 180 o 270)

Ejemplos:

post_document

Subir un nuevo documento a Paperless-NGX.

Parámetros:

• archivo: contenido de archivo codificado en Base64
• nombre_de_archivo: Nombre del archivo
• título (opcional): Título del documento
• creado (opcional): Fecha y hora en que se creó el documento (por ejemplo, "2024-01-19" o "2024-01-19 06:15:00+02:00")
• corresponsal (opcional): ID de un corresponsal
• document_type (opcional): ID de un tipo de documento
• storage_path (opcional): ID de una ruta de almacenamiento
• etiquetas (opcional): Matriz de identificaciones de etiquetas
• archive_serial_number (opcional): Número de serie del archivo
• custom_fields (opcional): Matriz de ID de campos personalizados

Operaciones de etiquetas

etiquetas de lista

Obtener todas las etiquetas.

crear_etiqueta

Crear una nueva etiqueta.

Parámetros:

• nombre: Nombre de la etiqueta
• color (opcional): código de color hexadecimal (por ejemplo, "#ff0000")
• coincidencia (opcional): Patrón de texto a combinar
• algoritmo_de_coincidencia (opcional): Uno de "cualquiera", "todos", "exacto", "expresión regular", "difuso"

Operaciones de corresponsalía

lista_correspondientes

Obtener todos los corresponsales.

crear_corresponsal

Crear un nuevo corresponsal.

Parámetros:

• nombre: Nombre del corresponsal
• coincidencia (opcional): Patrón de texto a combinar
• algoritmo_de_coincidencia (opcional): Uno de "cualquiera", "todos", "exacto", "expresión regular", "difuso"

Operaciones de tipo de documento

lista_tipos_de_documentos

Obtenga todos los tipos de documentos.

crear_tipo_de_documento

Crear un nuevo tipo de documento.

Parámetros:

• nombre: Nombre del tipo de documento
• coincidencia (opcional): Patrón de texto a coincidir
• algoritmo_de_coincidencia (opcional): Uno de "cualquiera", "todos", "exacto", "expresión regular", "difuso"

Manejo de errores

El servidor mostrará mensajes de error claros si:

• La URL o el token API de Paperless-NGX son incorrectos
• El servidor Paperless-NGX no está disponible
• La operación solicitada falla
• Los parámetros proporcionados no son válidos

Desarrollo

¿Quieres contribuir o modificar el servidor? Esto es lo que necesitas saber:

1. Clonar el repositorio
2. Instalar dependencias:

3. Realice sus cambios en server.js
4. Prueba localmente:

El servidor está construido con:

• litemcp : Un marco de TypeScript para crear servidores MCP
• zod : validación de esquemas basada en TypeScript

Documentación de la API

Este servidor MCP implementa puntos finales de la API REST de Paperless-NGX. Para más detalles sobre la API subyacente, consulte la documentación oficial .