PDF Agent MCP

# PDF Agent MCP 🌐 **[Visit the Landing Page](https://vlad-ds.github.io/pdf-agent-mcp/landing_page/)** for an overview and easy download ## ⚠️ Important Setup Instructions **Before using this extension, you MUST configure Claude Desktop properly:** ### Required Configuration 1. **Install Node.js LTS**: Visit [nodejs.org](https://nodejs.org/) and download the LTS version 2. **Configure Claude Desktop**: - Go to **Claude > Settings > Extensions > Advanced Settings** - **Disable** "Use Built-in Node.js for MCP" - Restart Claude Desktop **This extension will NOT work with Claude's built-in Node.js**. You must use your system's Node.js installation. ### Troubleshooting If you experience issues loading the extension: 1. Verify Node.js is installed: Run `node --version` in your terminal 2. Ensure "Use Built-in Node.js for MCP" is disabled in Claude Desktop settings 3. Restart Claude Desktop completely 4. Check the logs at `~/Library/Logs/Claude/mcp-server-PDF Agent MCP.log` (macOS) or `%LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log` (Windows) --- A Model Context Protocol server designed for agentic reading and selective PDF processing. Enables AI systems to efficiently navigate and extract content from PDFs without overwhelming context windows. ## Features - **Metadata Extraction**: Get PDF properties, page count, and file information - **Text Extraction**: Native text extraction with hybrid processing for better results - **Image Conversion**: Convert PDF pages to optimized images for visual analysis - **Content Search**: Pattern/regex search with context snippets - **Table of Contents**: Extract bookmarks and document outline - **Flexible Path Support**: Use absolute paths or relative paths from `~/pdf-agent/` ## Usage Guide PDF Agent MCP solves the common problem of context window overflow when working with PDFs in AI tools. **Important: Do not drag PDFs into the chat** - this will load the entire PDF content traditionally and bypass the intelligent processing. Instead, provide file paths or URLs to activate the PDF Agent tools for selective processing. ### How to Use **For Local PDFs:** - Provide the absolute file path to your PDF - Quick tip: Right-click your PDF → "Open with Chrome" → copy the address bar URL for the absolute path **For Online PDFs:** - Simply provide the PDF URL - the agent will download and process it locally ### Key Benefits - **Selective Reading**: The AI first examines metadata and outline, then opens only relevant pages - **Token Efficiency**: Avoids images when possible, uses them only when necessary for visual analysis - **Scalable**: Works with large documents (1000+ page textbooks) and multiple PDFs simultaneously - **Search Capability**: Built-in pattern/regex search across PDF content ### Approach This MCP uses **agentic search with simple tools** rather than complex alternatives: - No embedding creation, chunking, or vector storage required - No multi-agent coordination or handoff complexity - Just clean, effective tools that modern AI systems can use intelligently Perfect for researchers, students, and professionals working with extensive PDF libraries. ## AI Assistant Prompt for Optimal Usage **Copy this prompt into your AI assistant's custom instructions or context for best results:** ``` When working with PDFs using the PDF Agent MCP tools, follow this strategic approach: ### 1. Query Analysis & PDF Identification - **Think carefully** about the user's search query and information needs - **Identify which PDF(s)** are most likely to contain the answer - Consider the document type, domain, and likely structure based on the query ### 2. Exploratory Phase (Always Start Here) - **Get metadata** first using `get_pdf_metadata` to understand document size, creation date, and properties - **Extract table of contents** with `get_pdf_outline` to understand document structure and navigation - **Analyze the outline** to identify which sections are most relevant to the query ### 3. Strategic Content Extraction Based on the outline and metadata: - **Use page ranges** (`"5:10"`, `"20:"`) to focus on specific sections rather than entire documents - **Extract images** with `get_pdf_images` when visual content is critical (charts, diagrams, tables, equations) - **Choose text extraction strategy**: `hybrid` (default) for most cases, `native` for clean PDFs, `ocr` for scanned documents ### 4. Advanced Search Strategies - **Use multiple search queries** with different keywords and synonyms - **Apply regex patterns** for flexible matching: `/budget|cost|expense/gi` instead of single terms - **Combine searches**: Start broad, then narrow down with specific terms - **Use context characters** (150+ chars) to understand search result context - **Implement early stopping** with `max_results` for large documents ### 5. Iterative Refinement - **Start with targeted searches** based on outline analysis - **Follow up with broader searches** if initial queries don't yield results - **Extract specific page ranges** identified through search results - **Use visual analysis** (images) when text extraction seems incomplete or when layout matters ### 6. Performance Optimization - **Avoid processing entire large PDFs** - always use page ranges when possible - **Use search with early stopping** before extracting large sections - **Prefer search over full text extraction** for finding specific information - **Extract images selectively** only when visual analysis is needed ### 7. Multi-Document Workflows - **Process documents in parallel** when comparing multiple PDFs - **Use consistent search terms** across documents for comparison - **Combine results strategically** rather than processing everything at once ### Key Principles: - **Strategic before comprehensive**: Understand document structure before diving deep - **Search before extract**: Use pattern matching to locate relevant content first - **Visual when necessary**: Extract images only when text extraction is insufficient - **Iterative refinement**: Start targeted, expand scope as needed - **Context preservation**: Always maintain enough context around search results This approach maximizes efficiency, minimizes token usage, and provides more accurate, focused results than traditional "dump entire PDF" methods. ``` ## Installation ### Option 1: DXT Package (Recommended) 1. **First**, ensure you have completed the [Required Configuration](#required-configuration) above 2. Download the latest `pdf-agent-mcp.dxt` file from the releases 3. Double-click the `.dxt` file to install it in Claude Desktop ### Option 2: Manual Installation 1. **First**, ensure you have completed the [Required Configuration](#required-configuration) above 2. Clone this repository 3. Build the project: `npm install && npm run build` 4. Find your Claude Desktop config file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` Add the following: ```json { "mcpServers": { "pdf-agent": { "command": "node", "args": [ "PATH_TO_REPO/server/index.js" ] } } } ``` Replace `PATH_TO_REPO` with the actual path to your cloned repository. ## Development ```bash # Install dependencies npm install # Build the project npm run build # Create DXT package npm run build:dxt # Pack the final .dxt file for distribution dxt pack ``` ### Viewing Logs To debug issues, you can view the MCP server logs: ```bash # View logs (macOS) open "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log" # Stream logs in real-time (macOS) tail -f "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log" # Clear/delete logs (macOS) rm "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log" # View logs (Windows) notepad "%LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log" # Clear/delete logs (Windows) del "%LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log" ``` ## License MIT