# Paperless-ngx MCP for AI Agents AI Agent Connect > Paperless-ngx lets you turn your messy pile of PDFs, images, and scans into a searchable brain for your AI. Instead of digging through folders, you can just ask your agent to find that one specific tax form from three years ago or summarize a lease agreement. It connects directly to your existing Paperless-ngx instance, giving your AI the ability to read, organize, and manage your personal or business archive in real-time. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Endpoint:** https://edge.vinkius.com/vk_preview_ATPPyZ9x84oVznA3DvTkjjQfOt5pNtonNux3XF3j/ai-agent-connect - **Tags:** digital-archive, ocr, full-text-search, file-management, document-indexing, open-source ## Description Imagine having a personal librarian who has memorized every single piece of paper you've ever scanned. That's what happens when you hook up your Paperless-ngx instance to an AI agent. Instead of manually tagging files or squinting at blurry scans, you just tell your agent what you're looking for. It handles the heavy lifting of navigating your archive, pulling out the specific text you need, and organizing your metadata. If you're tired of "where did I put that?" being a daily hurdle, this is the fix. By listing this Connector on Vinkius, it becomes a standard way to bridge your private data with the reasoning power of your favorite AI client. You get to stop being a file manager and start being a person who actually uses the information you've collected. It's about moving from a static pile of documents to a dynamic knowledge base that actually talks back to you. ## Tools ### list_tags Get a list of every tag in your archive. Use this to see how your library is currently organized. ### list_documents Search and filter through your entire archive. Use this to find any file based on dates, tags, or keywords. ### create_correspondent Add a new contact or organization to your library. This helps your agent track who you interact with. ### delete_tag Remove a tag you no longer need. This helps keep your organizational labels clean. ### get_correspondent See the details for a specific contact or organization. It helps your agent identify who a document belongs to. ### get_document Pull all the metadata and OCR text for a single file. This lets your agent read the contents of a scan. ### get_document_type See the specific category details for a document. This helps the agent understand the nature of the file. ### list_correspondents See a full list of all your contacts and organizations. This helps your agent identify key entities in your archive. ### list_document_types See all the categories you've set up for your files. This helps your agent understand your filing system. ### preview_document Get a quick visual look at a document's contents. This helps you verify you've found the right file. ### thumb_document Grab a small thumbnail image of a document. This is perfect for quickly scanning through multiple results. ### update_correspondent Edit the information for a specific contact. Use this to keep your organization's directory up to date. ### update_document Change the metadata or tags on a specific file. This allows your agent to organize your library for you. ### update_document_type Modify the category settings for your documents. Use this to change how a file is classified in your archive. ### update_tag Edit the name or description of an existing tag. This keeps your organizational labels consistent. ### upload_document Send a new file to your Paperless-ngx instance. Use this to add new documents to your archive via chat. ### create_tag Add a new organizational tag to your archive. This lets you create new categories as you find them. ### list_saved_views See all your custom saved search filters. Use this to see your most-frequent archive queries. ### create_document_type Set up a new category for your documents. Use this to expand your filing system's structure. ### create_saved_view Save a specific search filter for later use. This helps your agent jump to your most-used results quickly. ### delete_correspondent Remove a contact from your archive. Use this to clean up your library of old or irrelevant entities. ### delete_document Permanently remove a file from your library. Use this to clean up your archive when a document is no longer needed. ### delete_document_type Remove a document category. Use this to simplify your filing system. ### delete_saved_view Delete a custom saved search filter. Use this to remove filters that are no longer useful. ### download_document Save the actual document file to your local machine. Use this when you need the original file for offline use. ### get_tag Look up the details of a specific tag. This provides context on how a certain label is being used. ## Prompt Examples **Prompt:** ``` Find all my electricity bills from last year and tell me the average monthly cost. ``` **Response:** ``` I've scanned your Paperless-ngx archive and found 12 electricity bills from 2023. | Month | Amount | |-------|--------| | Jan | $145.00 | | Feb | $152.20 | | Mar | $138.10 | | ... | ... | **Average Monthly Cost:** $148.50 Would you like me to download any of these for you? ``` **Prompt:** ``` I need to see the lease agreement for the office. Can you find it and tell me the monthly rent? ``` **Response:** ``` I found the document titled **'Office Lease Agreement - Suite 400'** in your archive. **Key Details:** * **Monthly Rent:** $2,500.00 * **Lease Term:** 36 Months * **Termination Clause:** Requires 90 days written notice. [View Preview Link] ``` **Prompt:** ``` Upload this new contract and tag it as 'Legal' and 'Active'. ``` **Response:** ``` I've successfully uploaded the document to your Paperless-ngx instance. **Status:** * **Action:** Uploaded * **Tags Applied:** Legal, Active * **Processing:** The system is currently running OCR to make the text searchable. ``` ## Capabilities ### Search your archive with full-text search Find any document instantly by typing keywords instead of clicking through folders. ### Upload files directly from chat Send new documents to your archive without leaving your conversation. ### Get visual previews and thumbnails See what a document looks like before you decide to open it. ### Manage tags and correspondents Create and update organizational labels and contact details on the fly. ### Extract OCR text for deep analysis Pull the full text from a scan so your agent can summarize or analyze the contents. ### Access saved search views Jump straight to your most-used filters and organizational structures. ## Use Cases ### Finding old utility bills A user asks for all electricity bills from 2022. The agent uses list_documents to find them and summarizes the totals. ### Reviewing lease agreements A legal assistant asks to find the "termination clause" in a lease. The agent uses get_document to read the OCR and gives the answer. ### Batch processing new uploads A user wants to tag all new PDFs from a specific company. The agent uses upload_document and update_tag to batch process them. ### Research synthesis A researcher asks for every paper related to "quantum dots." The agent finds the files, pulls the text, and creates a summary table. ## Benefits - Stop manual searching: Use list_documents to find any file instantly by typing what it is, not where it's stored. - Faster metadata updates: Use update_document and update_tag to keep your library organized without leaving your chat window. - Immediate visual context: Get a quick look at what you're dealing with using preview_document and thumb_document. - Automated data extraction: Use get_document to pull OCR text so your agent can summarize long contracts or bills. - Dynamic organization: Create new categories on the fly with create_correspondent and create_document_type as you find new files. - Instant file retrieval: Use download_document to grab the actual file when your agent finds the right one for you. ## How It Works The bottom line is it turns your static document archive into a conversational database. 1. Provide your Paperless-ngx API URL and Personal API Token in your client settings. 2. Subscribe to this Connector through the Vinkius catalog. 3. Ask your AI client to find, summarize, or organize any document in your library. ## Frequently Asked Questions **Does Paperless-ngx MCP work with my existing archive?** Yes, it connects directly to your current Paperless-ngx instance using your API URL and Personal API Token. **Can I use it to search my scanned receipts?** Yes, it uses the OCR text from your scans to find information, so you can ask about specific amounts or dates. **Does it let me download the files?** Yes, your agent can fetch the original document from your archive and provide a download link for you. **How does it handle my private data?** It uses your own private API credentials to communicate with your server, ensuring your data stays within your control. **Can I organize my files using just voice or chat?** Yes, you can tell your agent to create new tags, update contact details, or re-classify documents as you talk to it. **Is there a limit to how many documents it can see?** It can access everything that is hosted on your Paperless-ngx instance, making it a complete solution for your archive. **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.