Paperless MCP
# Paperless MCP
Search your [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) archive and read document text from an MCP client. The server runs locally over stdio and uses the Paperless REST API. You can enable tools for editing metadata, applying existing tags and uploading files.
Tested with Paperless-ngx 2.20.15 and 3.4.2.
## Setup
1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
2. In Paperless, open **My profile** and create an API token. The token inherits your account's permissions. Use an account with view permissions for the parts of the archive you want to share.
3. Clone the repository and install the locked dependencies.
```sh
git clone https://github.com/wouterrutgers/paperless-mcp.git
cd paperless-mcp
uv sync --locked
```
Use the base URL of your Paperless instance, including any subpath. For example, use `https://paperless.example.com` for an API at `https://paperless.example.com/api/`.
### Claude Desktop and other stdio clients
Add this entry to your client's MCP configuration. Replace the paths with the full paths to `uv` and your checkout.
```json
{
"mcpServers": {
"paperless": {
"command": "/path/to/uv",
"args": ["run", "--no-sync", "--project", "/path/to/paperless-mcp", "paperless-mcp"],
"env": {
"PAPERLESS_URL": "https://paperless.example.com",
"PAPERLESS_TOKEN": "your-api-token"
}
}
}
}
```
### Codex
Add this to your personal `~/.codex/config.toml`. Use the same paths and Paperless settings as above.
```toml
[mcp_servers.paperless]
command = "/path/to/uv"
args = ["run", "--no-sync", "--project", "/path/to/paperless-mcp", "paperless-mcp"]
env = { PAPERLESS_URL = "https://paperless.example.com", PAPERLESS_TOKEN = "your-api-token" }
```
Restart your client, then ask something like “Find my latest home insurance policy and link to the original in Paperless.”
## Enable writing
Set `PAPERLESS_ALLOW_WRITE` to `true` in the same `env` section to enable metadata and tag edits. The default is `false`. Your Paperless account needs permission to edit the documents in question.
To enable uploads as well, set `PAPERLESS_UPLOAD_DIR` to the full path of a folder on the computer running the MCP client. Give the client a filename relative to that folder, such as `insurance.pdf`. Paperless processes uploads in the background. The upload task ID lets the client check the result.
## Tools
| Tool | What it does |
| --- | --- |
| `search_documents` | Search by text or use Paperless query syntax. Filter by tag, correspondent or document type. |
| `get_document` | Get metadata and a link to the document in Paperless. |
| `read_document` | Read the text Paperless extracted, in chunks for longer documents. |
| `list_tags`, `list_correspondents`, `list_document_types` | Look up names and IDs for filters. |
| `update_document` | Edit the title, date, correspondent or document type. |
| `change_document_tags` | Apply or remove existing tags. |
| `upload_document`, `get_upload_status` | Queue a file for import and check its status. |
The server sends API requests to your configured Paperless instance. Your MCP client receives the requested metadata and text and may share it with its model provider. Keep the API token in your personal configuration.
## Development
Run the tests with `uv run --locked python -m unittest discover -s tests`.
## License
[MIT](LICENSE).
TDQS
Scored across 6 tools
The three list_* tools target clearly separate metadata types, and search_documents, get_document, and read_document separate discovery, metadata retrieval, and text reading. There is minor overlap because search_documents also returns metadata, but the boundaries remain workable.
All tools use snake_case with a clear verb_noun pattern: list_*, search_documents, get_document, and read_document. The convention is consistent across the entire surface.
Six tools are well scoped for a document lookup/retrieval interface. Each tool has a distinct role, and there is no obvious redundancy or missing slot from a count perspective.
The surface covers listing metadata, searching, metadata retrieval, and reading extracted text, but it is entirely read-only. It lacks core Paperless lifecycle operations such as uploading/creating documents and updating or deleting documents, tags, correspondents, or document types, which will cause failures for common management requests.