paperless-ngx-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Paperless-NGX MCP Server - A Model Context Protocol server enabling Claude AI to interact with Paperless-NGX document management systems. Supports two deployment modes:

• Stdio mode: Direct local connection for Claude Desktop
• HTTP/OAuth mode: Remote access for Claude.ai with Google Workspace authentication

Common Commands

npm install              # Install dependencies
npm start <url> <token>  # Run stdio mode (Claude Desktop)
npm run server           # Run HTTP server (Claude.ai)
npm run dev              # Development with auto-reload

Stdio mode can also use environment variables instead of CLI args:

PAPERLESS_URL=https://paperless.example.com PAPERLESS_TOKEN=abc123 npm start

Architecture

Entry Points

• src/index.js - Stdio entry point using LiteMCP. Registers all 50 tools directly and starts in stdio mode.
• src/server.js - HTTP/OAuth entry point using Express. Provides OAuth endpoints, SSE connections, MCP message handling at /mcp, and web UI.

Core Modules

API Client (src/api/PaperlessAPI.js)

• Wraps all Paperless-NGX REST API endpoints
• Handles authentication, error handling, and request building
• Maps camelCase parameters to snake_case for the API
• Uses FormData for file uploads, JSON for other requests

Tool Modules (src/tools/*.js)

• Each file exports a register*Tools(mcp, api) function
• Tools use Zod schemas for parameter validation
• Return MCP-formatted responses: { content: [{ type: 'text', text: '...' }] }
• 9 modules: documents, tags, correspondents, documentTypes, storagePaths, customFields, savedViews, shareLinks, system

Auth Modules (src/auth/*.js)

• OAuth 2.0 implementation with PKCE support
• discovery.js - .well-known endpoints
• registration.js - Dynamic client registration
• authorize.js - Authorization code generation
• token.js - JWT token issuance with refresh token rotation