Skip to main content
Glama
README.md
# paperless-mcp

An MCP server for [Paperless-ngx](https://docs.paperless-ngx.com/). It lets a Claude session
find documents and read their extracted custom fields — amounts, dates, providers — without
returning document text.

- Each caller acts as their own Paperless user. The server can see only what that user can.
- Five read tools: `list_schema`, `search_documents`, `get_document`, `summarize_field`,
  `run_saved_view`.
- Documents tagged `private`, and documents with no type, are returned as metadata only.
  Configured document types are left out entirely.
- Served over streamable HTTP at `/mcp`, behind Cloudflare Access; the Access JWT is
  re-validated in-process.

## Design and specs

The design and the EARS specs are kept in a separate, private specification repository,
under the segment `document-access` (prefix `DACC`). Code and tests here cite those specs as
`@spec DACC-…`, so a citation is a pointer to the requirement a line implements even when the
spec itself isn't public.

## Configuration

Environment variables, all prefixed `PAPERLESS_MCP_`:

| Variable | Meaning |
|---|---|
| `PAPERLESS_URL` | Base URL the server calls Paperless on. |
| `PAPERLESS_UI_URL` | Base URL used to build the document links it returns. |
| `ACCESS_TEAM_DOMAIN` | Cloudflare Access team domain, e.g. `team.cloudflareaccess.com`. |
| `ACCESS_AUDIENCE` | The Access application's audience tag. |
| `IDENTITIES` | JSON list of `{"email", "token_env", "mode"}`. `token_env` names the environment variable holding that caller's Paperless token; `mode` is `read`. |
| `EXCLUDED_DOCUMENT_TYPES` | JSON list of document type names left out of every result. Default `["School Record"]`. |
| `ALLOWED_HOSTS` | JSON list of `Host` values the MCP endpoint answers to. |
| `HOST`, `PORT` | Listen address. Default `0.0.0.0:8000`. |

The server refuses to start, and exits non-zero, when the identity map is unusable, when an
identity holds more than view permissions in Paperless, or when the `private` tag or an
excluded document type does not exist. It re-checks permissions hourly and exits if they
have grown.

Each tool call writes one JSON audit line to stdout: who called, which Paperless user it
acted as, the tool, the document ids returned. Never a value, a title or a search string.
A call refused before a tool runs (an unknown tool, arguments that do not fit the schema) writes
the same line with the error class.

## Image

`build-push.yml` publishes `registry.home.chaosbit.dev/paperless-mcp` on every push to
`main`, and only after `ci.yml` passes on that commit. It reads four secrets from the
`release` environment, which only `main` can deploy to; they're listed at the top of the
workflow.

## Development

```sh
uv sync
uv run ruff check .
uv run mypy src
uv run pytest -q
```

## License

[MIT](LICENSE)