list_documents
List and filter documents in Paperless-NGX by title, correspondent, document type, tag, storage path, or creation date. Use specific ID filters for accurate results, ensuring precise document retrieval tailored to your search criteria.
Instructions
List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| correspondent | No | ||
| created__gte | No | ||
| created__lte | No | ||
| document_type | No | ||
| ordering | No | ||
| page | No | ||
| page_size | No | ||
| search | No | ||
| storage_path | No | ||
| tag | No |
Implementation Reference
- src/tools/documents.ts:166-188 (handler)Handler function for the 'list_documents' tool. Constructs a query string from input parameters, fetches documents via PaperlessAPI.getDocuments, and enhances the response using convertDocsWithNames.withErrorHandling(async (args, extra) => { if (!api) throw new Error("Please configure API connection first"); const query = new URLSearchParams(); if (args.page) query.set("page", args.page.toString()); if (args.page_size) query.set("page_size", args.page_size.toString()); if (args.search) query.set("search", args.search); if (args.correspondent) query.set("correspondent__id", args.correspondent.toString()); if (args.document_type) query.set("document_type__id", args.document_type.toString()); if (args.tag) query.set("tags__id", args.tag.toString()); if (args.storage_path) query.set("storage_path__id", args.storage_path.toString()); if (args.created__date__gte) query.set("created__date__gte", args.created__date__gte); if (args.created__date__lte) query.set("created__date__lte", args.created__date__lte); if (args.ordering) query.set("ordering", args.ordering); const docsResponse = await api.getDocuments( query.toString() ? `?${query.toString()}` : "" ); return convertDocsWithNames(docsResponse, api); }) );
- src/tools/documents.ts:154-165 (schema)Input schema (Zod) defining parameters for filtering and paginating documents in the 'list_documents' tool.{ page: z.number().optional(), page_size: z.number().optional(), search: z.string().optional(), correspondent: z.number().optional(), document_type: z.number().optional(), tag: z.number().optional(), storage_path: z.number().optional(), created__date__gte: z.string().optional(), created__date__lte: z.string().optional(), ordering: z.string().optional(), },
- src/tools/documents.ts:151-188 (registration)Registration of the 'list_documents' tool on the MCP server using server.tool(), including description, input schema, and handler.server.tool( "list_documents", "List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results.", { page: z.number().optional(), page_size: z.number().optional(), search: z.string().optional(), correspondent: z.number().optional(), document_type: z.number().optional(), tag: z.number().optional(), storage_path: z.number().optional(), created__date__gte: z.string().optional(), created__date__lte: z.string().optional(), ordering: z.string().optional(), }, withErrorHandling(async (args, extra) => { if (!api) throw new Error("Please configure API connection first"); const query = new URLSearchParams(); if (args.page) query.set("page", args.page.toString()); if (args.page_size) query.set("page_size", args.page_size.toString()); if (args.search) query.set("search", args.search); if (args.correspondent) query.set("correspondent__id", args.correspondent.toString()); if (args.document_type) query.set("document_type__id", args.document_type.toString()); if (args.tag) query.set("tags__id", args.tag.toString()); if (args.storage_path) query.set("storage_path__id", args.storage_path.toString()); if (args.created__date__gte) query.set("created__date__gte", args.created__date__gte); if (args.created__date__lte) query.set("created__date__lte", args.created__date__lte); if (args.ordering) query.set("ordering", args.ordering); const docsResponse = await api.getDocuments( query.toString() ? `?${query.toString()}` : "" ); return convertDocsWithNames(docsResponse, api); }) );
- src/api/documentEnhancer.ts:23-75 (helper)Helper function used by the handler to enhance document data with human-readable names for correspondents, types, tags, and custom fields, and format as MCP CallToolResult.export async function convertDocsWithNames( document: Document, api: PaperlessAPI ): Promise<CallToolResult>; export async function convertDocsWithNames( documentsResponse: DocumentsResponse, api: PaperlessAPI ): Promise<CallToolResult>; export async function convertDocsWithNames( input: Document | DocumentsResponse, api: PaperlessAPI ): Promise<CallToolResult> { if ("results" in input) { const enhancedResults = await enhanceDocumentsArray( input.results || [], api ); return { content: [ { type: "text", text: enhancedResults?.length ? JSON.stringify({ ...input, results: enhancedResults, }) : "No documents found", }, ], }; } if (!input) { return { content: [ { type: "text", text: "No document found", }, ], }; } const [enhanced] = await enhanceDocumentsArray([input], api); return { content: [ { type: "text", text: JSON.stringify(enhanced), }, ], }; }
- src/index.ts:69-69 (registration)Call to registerDocumentTools which includes the 'list_documents' tool registration on the main MCP server.registerDocumentTools(server, api);