Skip to main content
Glama
chrisguidry

paperless-mcp

by chrisguidry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PAPERLESS_URLYesThe URL of your paperless-ngx instance, e.g. https://paperless.example.com
PAPERLESS_TOKENYesYour paperless-ngx API token, generated in your profile

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": true
}
logging
{}
prompts
{
  "listChanged": true
}
resources
{
  "subscribe": false,
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
search_documentsA

Search and filter documents in the archive.

All parameters combine as AND conditions, except that query and more_like_document_id cannot be used together. query is full-text search over document contents using tantivy syntax: plain terms ("electric bill"), boolean operators ("chase AND (mortgage OR escrow)"), field prefixes ("correspondent:university", "type:invoice", "tag:unpaid", "created:[2020 to 2023]"), and wildcards ("electr*"). Notes and custom fields are structured fields with dotted paths: "notes.note:reimbursed", "custom_fields.value:overdue", "custom_fields.name:warranty". Plain terms do NOT match them, only titles and content. Full-text results include a search_hit with highlights.

more_like_document_id finds documents whose text is similar to one document's, ranked by similarity in search_hit.rank. The results leave out that document itself, and the other filters narrow them. Leave ordering unset to keep the ranking.

To find unfiled documents, use is_in_inbox=true, or has_tags, has_correspondent, has_document_type, or has_storage_path set to false.

custom_field_query compares custom field values, like "Amount over 100" or "Warranty Expires before 2027-01-01". Every field type supports exact, in, exists, and isnull. Date, integer, float, and monetary fields add gt, gte, lt, lte, and range. String, URL, long text, and monetary fields add icontains, istartswith, and iendswith. Document link fields add contains. Paperless refuses an operator that the field's type does not support.

Each result carries a uri, which you can read as an MCP resource for the document's full text, and a web_url that links to the document in the Paperless web UI. Read paperless://documents/{id}/notes for a document's notes, or call get_document for its notes and custom field values.

get_documentA

Get a single document's full metadata, with its notes and custom fields.

The preferred way to read a document's text is its MCP resource at paperless://documents/{document_id}.

list_tagsA

List tags.

Use the returned IDs with search_documents(tag_ids=[...]).

list_correspondentsA

List correspondents: the people and organizations that documents are from or to.

Use the returned IDs with search_documents(correspondent_id=...).

list_document_typesA

List document types, like invoice or receipt.

Use the returned IDs with search_documents(document_type_id=...).

list_storage_pathsA

List storage paths: the filing locations of documents.

Use the returned IDs with search_documents(storage_path_id=...).

list_custom_fieldsA

List the custom fields defined in the archive.

get_document returns a document's custom field values by field ID. A select field's value is the id of one of the field's select_options. Search custom field values with search_documents, using a query like "custom_fields.value:overdue".

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct operation: one broad search, one document fetch, and five entity-specific listers. The list_* tools could superficially look alike, but each names a clearly different Paperless resource and explicitly cross-references the corresponding search parameter, leaving no realistic misselection risk.

Naming Consistency5/5

All tools follow a clean verb_noun snake_case pattern (search_documents, get_document, list_tags, list_correspondents, list_document_types, list_storage_paths, list_custom_fields). No mixed casing or stray verbs.

Tool Count5/5

Seven tools is well-scoped: one flexible search, one detail fetcher, and the minimum set of lookup tools needed to resolve IDs for filtering. Nothing appears redundant or padding the surface.

Completeness3/5

The surface is entirely read-only: search, get, and list exist but there is no upload_document, update_document, delete_document, or create/update for tags, correspondents, document types, storage paths, or custom fields. Core retrieval workflows are covered, but lifecycle operations for a document management archive are notably absent.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources