Paperless-ngx MCP

Version: 2.2.1

paperless-ngx-mcp provides a typed Python client, current intent/condensed/verbose MCP surfaces, an optional A2A agent, and a governed epistemic-graph connector for the standard Paperless-ngx API.

The package is deployment-neutral. It contains no instance profile, connection value, credential, certificate, user record, customized taxonomy, or durable source content.

Capabilities

• Manage documents, notes, correspondents, tags, document types, storage paths, custom fields, and saved views.
• Search, inspect tasks and statistics, acknowledge tasks, and inspect the provider schema and status.
• Upload only approved files inside the AgentConfig workspace boundary.
• Authenticate with a fixed service token projected by the MCP fleet secret resolver or with request-scoped RFC 8693 delegation.
• Apply system trust, private CA bundles, mTLS, and proxy policy through a shared mandatory-verification TLS profile.
• Project keyed, content-free document topology for governed ChangeEnvelope ingestion.
• Contribute one complete paperless-ngx-operations skill and data-only ontology, source-preset, and prompt providers.

MCP tools

Condensed tools accept action plus a JSON-object string in params_json. Verbose mode exposes the same public client methods one-to-one. The generated table is derived from the live server surface.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

4 action-routed tool(s) · 36 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Install

uvx --from "paperless-ngx-mcp[mcp]" paperless-ngx-mcp

provides the full Epistemic Graph runtime on the current dependency line.

AgentConfig boundary

The checked-in MCP catalog contains references only:

{
  "mcpServers": {
    "paperless-ngx-mcp": {
      "command": "uvx",
      "args": ["--from", "paperless-ngx-mcp[mcp]", "paperless-ngx-mcp"],
      "env": {
        "PAPERLESS_URL": "env://PAPERLESS_URL",
        "PAPERLESS_TOKEN": "env://PAPERLESS_TOKEN",
        "PAPERLESS_INGESTION_PSEUDONYMIZATION_KEY": "env://PAPERLESS_INGESTION_PSEUDONYMIZATION_KEY",
        "TLS_PROFILE": "env://TLS_PROFILE",
        "TLS_PROFILES_REF": "env://TLS_PROFILES_REF",
        "WORKSPACE_PATH": "env://WORKSPACE_PATH",
        "MCP_TOOL_MODE": "intent",
        "LANGFUSE_CAPTURE_CONTENT": "false"
      }
    }
  }
}

Arbora reads this catalog through AgentConfig.MCP_CONFIG. Map the runtime aliases to approved env://, vault://, or secret:// runtime sources with AgentConfig.MCP_FLEET_SECRET_REFS. The connector has no packaged URL or credential default and requires HTTPS.

TLS is resolved by resolve_configured_tls_profile("paperless"). Select system trust or a runtime profile with TLS_PROFILE / TLS_PROFILES_REF; do not add a verification boolean or commit trust material.

Validate the reference boundary without displaying resolved values:

agent-connector-sdk-doctor --only config transport_security mcp_fleet_secrets mcp_fleet

Privacy-preserving graph synchronization

paperless_ingestion_projection transforms provider records in memory into keyed opaque references and structural relationships. paperless_ingest_projection commits that same projection through Agent Connector SDK' governed ChangeEnvelope path.

The durable projection excludes OCR text, titles, notes, names, filenames, storage locations, timestamps, URLs, raw bytes, and provider identifiers. It requires a deployment-owned pseudonymization key of at least 32 bytes. Activation remains blocked until the central capability compiler produces and validates the reviewed signed bundle; this repository intentionally does not manufacture signed release artifacts.

Documentation

• Configuration
• Installation
• Usage
• Deployment
• Architecture
• Concepts

Security

• No arbitrary REST escape hatch or password-to-token action is exposed.
• Pagination is same-origin and bounded; redirects do not carry provider credentials.
• HTTP errors omit response bodies, connection values, parameters, and record content.
• Tool handlers do not echo malformed JSON or provider exception text.
• Uploads are constrained to a configured workspace root and a fixed size ceiling.
• Telemetry examples default to content capture disabled.

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

19 package + 19 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Licensed under the MIT License.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.