Local Documents MCP Server

# 📚 Local Documents MCP Server A Model Context Protocol (MCP) server for interacting with local documents on Windows systems. This server provides tools to list, load, and process documents with support for OCR on scanned PDFs. ## ✨ Features - **📁 Document Discovery**: List all documents in a specified directory - **⚡ Document Processing**: Convert various document formats to markdown - **🔍 OCR Support**: Extract text from scanned PDFs using Tesseract OCR - **🎯 Token Management**: Automatic content truncation based on token limits - **📄 Multi-format Support**: Handle Word docs, PDFs, PowerPoint, Excel, and more ## 🛠️ Tools Available - `list_documents`: Find documents by path, name, and extension - `load_documents`: Extract document content as markdown - `load_scanned_document`: Extract text from scanned PDFs using OCR ## 💻 System Requirements - **Operating System**: Windows 10/11 - **Python**: 3.13 or higher - **Package Manager**: [uv](https://docs.astral.sh/uv/) (recommended) ## 📋 Prerequisites Installation ### 1. 🐍 Python 3.13 Download and install Python 3.13 from [python.org](https://www.python.org/downloads/) ### 2. ⚡ UV Package Manager Install uv using pip: ```powershell pip install uv ``` ### 3. 📖 Poppler for Windows **Purpose**: Required for PDF processing and conversion to images for OCR. 1. Download the latest Poppler Windows release from: https://github.com/oschwartz10612/poppler-windows/releases/ 2. Extract the ZIP file to: ``` D:\Program Files\poppler-24.08.0 ``` 3. The Poppler binaries should be located at: ``` D:\Program Files\poppler-24.08.0\Library\bin ``` **Alternative locations**: You can install Poppler in any directory, just make sure to update the `.env` file with the correct path. ### 4. 👁️ Tesseract OCR **Purpose**: Required for extracting text from scanned documents and images. 1. Download Tesseract for Windows from: https://github.com/UB-Mannheim/tesseract/wiki 2. Install Tesseract following the installer instructions 3. Make sure Tesseract is added to your system PATH, or note the installation directory ## 🚀 Project Installation ### 1. 📥 Clone or Download the Project ```powershell git clone <your-repo-url> cd LocalDocs ``` ### 2. 📦 Install Python Dependencies ```powershell uv sync ``` This will install all required dependencies from `pyproject.toml`: - `markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.2` - Document conversion - `mcp[cli]>=1.10.1` - MCP server framework - `opencv-python>=4.11.0.86` - Image processing - `pdf2image>=1.17.0` - PDF to image conversion - `pytesseract>=0.3.13` - Tesseract OCR wrapper - `python-dotenv>=1.1.1` - Environment variable management - `tiktoken>=0.9.0` - Token counting ### 3. ⚙️ Configure Environment Variables Create or update the `.env` file in the project root: ```env POPPLER_PATH="D:\\Program Files\\poppler-24.08.0\\Library\\bin" ``` **Note**: Update the path to match your Poppler installation location. ## 🔧 Configuration for MCP Clients ### 🤖 Claude Desktop Configuration Add the following configuration to your Claude Desktop `config.json` file: - **First argument**: Path to your documents directory - Example: `"C:\\Users\\YourUsername\\Documents\\MyDocuments"` - Use double backslashes for Windows paths in JSON - **Second argument**: Maximum tokens per document - Example: `"30000"` - Adjust based on your needs and Claude's token limits ### 📝 Example Configurations **For different document locations**: ```json { "mcpServers": { "local-documents": { "command": "uv", "args": [ "--directory", "C:\\Users\\YourUsername\\Documents\\LocalDocs", "run", "server.py", "C:\\Users\\YourUsername\\Documents\\MyDocuments", "30000" ] } } } ``` ## 🎯 Usage ### 🚀 Starting the Server The server is automatically started when Claude Desktop loads with the configured settings. ### 🔄 Available Operations 1. **📋 List Documents**: Discover all documents in your configured directory 2. **📄 Load Standard Documents**: Process Word docs, PDFs, PowerPoint, Excel files 3. **🔍 Load Scanned Documents**: Use OCR to extract text from scanned PDFs ### 📊 Response Format The server returns structured responses with: - Document paths and metadata - Token usage information - Processing time (for OCR operations) - Extracted content in markdown format ## 🛠️ Troubleshooting ### ⚠️ Common Issues 1. **🔍 Poppler not found** - Verify Poppler installation path - Check `.env` file configuration - Ensure path uses double backslashes in Windows 2. **👁️ Tesseract not found** - Verify Tesseract installation - Add Tesseract to system PATH - Restart command prompt/PowerShell 3. **🔐 Permission denied errors** - Ensure the document directory is accessible - Check file permissions - Run as administrator if necessary 4. **❌ Import errors** - Verify all dependencies are installed: `uv sync` - Check Python version: `python --version` - Ensure you're using Python 3.13 5. **⏳ Large document processing** - Reduce token limit for better performance - Consider splitting large documents - Monitor memory usage during OCR operations ### 🐛 Debug Information To get more detailed error information, check the Claude Desktop logs or run the server manually in a PowerShell window. ## 📁 File Structure ``` LocalDocs/ ├── server.py # Main MCP server ├── pyproject.toml # Project dependencies ├── .env # Environment configuration ├── README.md # This documentation ├── src/ │ └── instructions.md # Assistant instructions └── utils/ ├── __init__.py ├── markitdown.py # Document conversion ├── max_tokens.py # Token management ├── ocr.py # OCR processing ├── path_files.py # File discovery └── prompts.py # Instruction loading ``` ## 📄 Supported Document Formats - **📊 Microsoft Office**: .docx, .xlsx, .pptx - **📖 PDF**: Regular PDFs and scanned PDFs (via OCR) ## ⚡ Performance Considerations - **🔍 OCR Processing**: Scanned documents take significantly longer to process - **🎯 Token Limits**: Adjust based on your document sizes and Claude's context window - **💾 Memory Usage**: Large documents and OCR operations can be memory-intensive ## 🤝 Contributing When contributing to this project: 1. Ensure compatibility with Windows and Python 3.13 2. Test with various document formats 3. Verify OCR functionality with scanned documents 4. Update documentation for any new features ## 📚 Related Documentation - [MCP Documentation](https://modelcontextprotocol.io/) - [Claude Desktop MCP Guide](https://claude.ai/download) - [PDF2Image](https://github.com/Belval/pdf2image) - [Poppler PDF Processing](https://github.com/oschwartz10612/poppler-windows/releases/) - [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki) - [MarkItDown](https://github.com/microsoft/markitdown) ## 🗺️ Roadmap and Future Enhancements ### 🔮 Planned Features - **🧠 Vector Storage and RAG Integration**: Future versions will include vectorial document storage to: - Reduce token consumption by avoiding repeated text extraction - Enable semantic search across document collections - Provide more efficient document retrieval and chunking - Support for persistent document indexing - **🔍 Enhanced OCR Validation**: Currently, OCR functionality for scanned books has not been fully validated and may encounter issues with: - Complex layouts and formatting - Multi-column documents - Poor quality scans - Non-standard fonts or languages ### 💡 Current Recommendations #### 🚀 For Large Context Models - **🤖 Gemini Models**: With 1M+ token context windows, you can process very long documents without truncation - **🎯 Token Management**: Current implementation supports up to 128K tokens by default, but can be adjusted for larger context models - **📖 Document Processing**: Consider using higher token limits (e.g., 500K-1M) when working with: - Complete books or long reports - Multiple related documents - Comprehensive document analysis #### ⚠️ Limitations to Consider - **🔍 OCR Reliability**: Scanned document processing is experimental and may require manual validation - **⏳ Processing Time**: Large documents and OCR operations can be time-intensive - **💾 Memory Usage**: High-resolution scanned documents may require significant system resources