# Paperless-ngx MCP > Paperless-ngx connects your digital archive to any AI agent, turning massive document folders into a searchable knowledge base. Use it to find tax receipts, contract details, or research papers instantly by asking natural questions. Manage tags, upload new files, and retrieve OCR text directly from your existing records. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** digital-archive, ocr, full-text-search, file-management, document-indexing, open-source ## Description Stop wading through endless folders just to find one date or name. This connector lets you treat your document archive like a librarian that knows every word in it. Instead of manually searching folder structures or running complex queries, you simply ask your agent for what you need—and get an answer based on the full text and metadata of your files. You can use dedicated functions to upload new documents, organize them by creating tags or updating correspondents, or pull out a specific document's details. If you're managing records across different systems, connecting it through Vinkius gives you one place to access this power from any compatible client. It’s about turning static files into actionable data. ## Tools ### list_tags Provides a complete list of every tag currently in use in the system. ### delete_tag Removes an unused tag from your system. ### download_document Retrieves the original physical file for a selected document ID. ### get_correspondent Fetches all details about an existing correspondent by name or ID. ### get_document Retrieves the full metadata and OCR text for a specific document file. ### get_document_type Fetches details about a defined document type category. ### get_tag Retrieves the full definition of a tag by its ID. ### list_correspondents Shows a list of all correspondents currently tracked in your archive. ### list_document_types Displays all the document types and categories you have defined. ### list_documents Searches and lists documents across the entire archive, supporting filters by date or keyword. ### preview_document Generates and shows a visual preview link for a selected document. ### thumb_document Creates and retrieves a small thumbnail image for a document. ### update_correspondent Modifies the details of an existing correspondent record. ### update_document Changes the metadata (like tags or date) associated with a specific document. ### update_document_type Modifies the definition of an existing document category. ### update_tag Updates the description or name of a tag. ### upload_document Ingests and processes a new physical file into your document archive. ### create_tag Generates a new keyword or tag to classify documents. ### create_correspondent Adds a new individual or company name used in your archive. ### create_document_type Defines and adds a new category for documents, such as 'Invoice' or 'Lease Agreement'. ### create_saved_view Saves a specific filter combination so you can easily recall that view later. ### list_saved_views Lists all predefined filter views that you have saved for quick access. ### delete_correspondent Permanently removes an individual or company from your correspondent list. ### delete_document Removes a specific document file from the archive. ### delete_document_type Deletes an existing document category definition. ### delete_saved_view Removes a previously saved filter view. ## Prompt Examples **Prompt:** ``` Search for all documents related to 'Electricity Bill' from 2023. ``` **Response:** ``` I've searched your archive using `list_documents`. I found 3 documents: 'Jan 2023 Electricity' (ID: 101), 'Feb 2023 Electricity' (ID: 105), and 'March 2023 Electricity' (ID: 110). Would you like to see the details of one of them? ``` **Prompt:** ``` Upload a new document titled 'Contract 2024' with tag ID 12. ``` **Response:** ``` Processing the upload... I've successfully used `upload_document` to add 'Contract 2024'. It has been assigned ID 250 and is now being processed by Paperless-ngx for OCR. ``` **Prompt:** ``` Get the full content and a preview of document ID 42. ``` **Response:** ``` I've retrieved the data for document 42 using `get_document` and `preview_document`. The document is a 'Lease Agreement'. The OCR text mentions a monthly rent of $1,200. I've also generated a preview link for you. ``` ## Capabilities ### Search and Discover Records Find specific documents by querying the full text, date ranges, or predefined organizational tags. ### Manage Document Lifecycle Upload new files to the archive, download originals for review, or delete outdated records. ### Organize Metadata and Tags Create, update, or retrieve tags and document types to keep your entire library consistently organized. ### Inspect Document Content Fetch the complete OCR text and detailed metadata for any file so your agent can analyze its contents fully. ## Use Cases ### Verifying Contract Dates A paralegal needs to know the start date of every contract signed by 'Smith & Sons'. They ask their agent to list documents and filter by correspondent. The agent uses `list_documents` and `get_correspondent` to pull up all relevant files, providing a concise timeline instead of a folder dump. ### Processing Bulk Invoices An ops manager receives 50 invoices. Instead of manually uploading them, they use the agent to upload_document in batches. The agent then uses `create_tag` and `update_document` immediately after ingestion, ensuring every file is categorized as 'Invoice' and tagged with the correct vendor name. ### Researching Historical Data A researcher needs all documents related to 'Project Chimera' from 2018. They ask their agent for a list of documents, specifying both keywords and the date range. The agent calls `list_documents`, returning only the relevant records so they can start writing immediately. ### Updating Client Records A legal team updates client information. Instead of logging into two different systems, they tell their agent to update the correspondent details using `update_correspondent`, ensuring all archival files linked to that person reflect the current contact info. ## Benefits - Find exactly what you need without digging through folders. The `list_documents` tool allows your agent to search across keywords, dates, and tags instantly. No more manual filtering. - Consolidate all document data into one place. By using the MCP, your AI client can access every detail of a file via `get_document`, giving you full OCR text for analysis. - Maintain perfect order with metadata management. You can use tools like `create_tag` and `update_document` to ensure new files are classified correctly right away. - Visualize and manage your library instantly. The agent can provide a quick visual context using `preview_document`, so you don't have to download every file just to check it out. - Build robust reporting workflows. By listing all document types (`list_document_types`) or saved views (`list_saved_views`), your AI client builds reports based on consistent, predefined structures. ## How It Works The bottom line is you tell the AI what you want in plain English; it handles the complex API calls and retrieval logic for you. 1. Subscribe to this MCP and provide the necessary Paperless-ngx API URL and Personal API Token. 2. Connect your preferred AI client (Claude, Cursor, etc.) to Vinkius via the MCP connection point. 3. Directly ask your agent questions about your documents. The agent will call the appropriate tools to search, retrieve data, or execute actions. ## Frequently Asked Questions **How do I search my documents with Paperless-ngx MCP?** You use the agent and ask it to list documents. The underlying tool, `list_documents`, allows you to specify filters like dates or keywords in your prompt. **Can I upload new files using the Paperless-ngx MCP?** Yes. You use the `upload_document` tool. The agent handles sending the file and ensuring it gets processed by Paperless-ngx for OCR indexing. **What if a document needs more tags? Can I update them with Paperless-ngx MCP?** You can use `update_document` to change metadata, or you can call the specific `create_tag` tool if the tag doesn't exist yet. **Do I need API tokens for Paperless-ngx MCP?** Yes. You must provide your Personal API Token and API URL when subscribing to this MCP so the agent can authenticate and talk to your instance. **Can I retrieve just the text from a document using Paperless-ngx MCP?** Absolutely. The `get_document` tool retrieves complete OCR text, allowing your AI client to read and summarize the content without needing a visual preview. **Can I search for documents using specific tags or date ranges?** Yes. The `list_documents` tool allows you to filter by `tags__id__in` and `created__date__gte`. You can also perform a full-text search using the `query` parameter. **Is it possible to see a preview of a document without downloading the whole file?** Absolutely. Use the `preview_document` or `thumb_document` tools to get visual representations of the document content directly through the agent. **Can I create new organization categories like tags or correspondents via AI?** Yes, you have full management capabilities. You can use `create_tag`, `create_correspondent`, and `create_document_type` to organize your archive on the fly.