Compose examples¶

paperless-mcp runs next to a Paperless-ngx server you already have. Pick the example that matches how Paperless is deployed: in the same compose file, or as its own compose project. Both are in the repo's examples/ directory.

Don't have Paperless-ngx yet?¶

paperless-mcp connects to an existing Paperless-ngx server. To set one up, follow Paperless's own setup guide, then come back here.

In Paperless's compose file¶

Add the paperless-mcp service and the mcp-oauth volume to the docker-compose.yaml that runs Paperless. Its settings go in a separate paperless-mcp.env, so they don't mix with the env files Paperless already uses. Copy paperless-mcp.env.example to paperless-mcp.env next to the compose file, adjust it, and run docker compose up -d paperless-mcp.

docker-compose.yamlpaperless-mcp.env

# Add paperless-mcp and its volume to the compose file that runs Paperless-ngx.
# Copy paperless-mcp.env.example to paperless-mcp.env next to it, then:
#   docker compose up -d paperless-mcp
services:
  webserver:
    # ... your existing Paperless-ngx service ...

  paperless-mcp:
    image: ghcr.io/marceltov/paperless-mcp:latest
    container_name: paperless-mcp
    restart: unless-stopped
    depends_on:
      - webserver
    env_file: paperless-mcp.env
    volumes:
      # OAuth logins survive container updates (unused with tokens only).
      - mcp-oauth:/data
    ports:
      - "8081:8081"

volumes:
  mcp-oauth:

# Paperless-ngx's address on the compose network: its service name, port 8000.
PAPERLESS_URL=http://webserver:8000

# Optional: enable OAuth login. Leave both empty for API tokens only.
# Public HTTPS address of this server, behind your reverse proxy.
MCP_BASE_URL=
# Encrypts stored logins. Generate once with: openssl rand -hex 32
MCP_OAUTH_SECRET=

# Optional: which toolsets become tools (comma-separated, or "all").
# Empty uses the defaults: documents and their metadata, no administration.
MCP_TOOLSETS=

# Optional: accept only these Host headers, comma-separated host[:port].
MCP_ALLOWED_HOSTS=

Both services share the compose network, so webserver resolves to your Paperless container.

As a separate compose project¶

Use this when you'd rather keep paperless-mcp out of Paperless's compose file. It joins the Docker network Paperless is already on. Put the files in their own folder, copy .env.example to .env, adjust it, and run docker compose up -d.

docker-compose.yaml.env

# paperless-mcp next to an existing Paperless-ngx, as its own compose project.
# Copy .env.example to .env, adjust it, then: docker compose up -d
services:
  paperless-mcp:
    image: ghcr.io/marceltov/paperless-mcp:latest
    container_name: paperless-mcp
    restart: unless-stopped
    env_file: .env
    volumes:
      # OAuth logins survive container updates (unused with tokens only).
      - mcp-oauth:/data
    ports:
      - "8081:8081"
    networks:
      - paperless

networks:
  # The Docker network your Paperless-ngx container is already on.
  paperless:
    external: true
    name: ${PAPERLESS_NETWORK:?set PAPERLESS_NETWORK in .env}

volumes:
  mcp-oauth:

# Docker network your Paperless-ngx container is on; find it with `docker network ls`.
# A compose project named "paperless" creates "paperless_default".
PAPERLESS_NETWORK=paperless_default

# Paperless-ngx's address on that network: its service or container name, port 8000.
PAPERLESS_URL=http://webserver:8000

# Optional: enable OAuth login. Leave both empty for API tokens only.
# Public HTTPS address of this server, behind your reverse proxy.
MCP_BASE_URL=
# Encrypts stored logins. Generate once with: openssl rand -hex 32
MCP_OAUTH_SECRET=

# Optional: which toolsets become tools (comma-separated, or "all").
# Empty uses the defaults: documents and their metadata, no administration.
MCP_TOOLSETS=

# Optional: accept only these Host headers, comma-separated host[:port].
MCP_ALLOWED_HOSTS=

To find PAPERLESS_NETWORK, run docker network ls, or docker inspect <paperless container> to see which network Paperless is on. PAPERLESS_URL uses Paperless's service or container name on that network.

Turning on OAuth¶

In either example, fill in MCP_BASE_URL and MCP_OAUTH_SECRET in the env file and recreate the container with docker compose up -d. Once the file holds the secret, keep it private (chmod 600) and out of version control. Every setting is described under Configuration.