gmdeckard/pdf-mcp-server
If you are the rightful owner of pdf-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
The PDF MCP Server is a comprehensive Model Context Protocol server designed to enable AI assistants to read, analyze, and extract content from PDF files.
PDF MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like GitHub Copilot and Claude Desktop to read and analyze PDF files with advanced features including password support, OCR, and enhanced table extraction.
Features
- Extract text from PDF files
- Support for password-protected PDFs
- Extract tables with enhanced detection using pdfplumber
- Extract images and perform OCR on scanned documents using tesseract
- Analyze PDF structure and metadata
- Memory optimization for large files
- Automatic Python virtual environment setup
- Cross-platform support (Linux, macOS, Windows including VS Code on Windows)
- Graceful degradation when optional dependencies are unavailable
Installation Options
Option 1: Global Installation (Persistent Across Workspaces)
For a persistent installation that works from any directory:
# Clone and install globally
git clone https://github.com/gmdeckard/pdf-mcp-server.git
cd pdf-mcp-server
npm install
npm run build
npm install -g .
# Now you can use 'pdf-mcp-server' from anywhere
pdf-mcp-server
# Or install directly from npm (when published)
npm install -g pdf-mcp-server
Important Notes for Global Installation:
- The Python virtual environment (
venv/) stays in the original clone directory - Enhanced table extraction with pdfplumber will work as long as the original directory exists
- If you delete the original directory, only basic PDF reading will work
- For full portability, ensure Python has pdfplumber installed globally:
pip install pdfplumber
Option 2: Local Installation (Per-Project)
For installation in a specific project directory:
# Clone the repository
git clone https://github.com/gmdeckard/pdf-mcp-server.git
cd pdf-mcp-server
# Install all dependencies (creates Python venv automatically)
npm install
# Build the server
npm run build
# Run from this directory only
npm start
The installation automatically:
- Creates a Python virtual environment in ./venv/ (Windows: venv\Scripts, Unix: venv/bin/)
- Installs pdfplumber for enhanced table extraction
- Attempts to install system dependencies (poppler-utils, tesseract-ocr)
- Falls back gracefully if optional dependencies cannot be installed
Manual System Dependencies (if needed)
If the automatic installation fails for system dependencies:
# Ubuntu/Debian:
sudo apt-get install poppler-utils tesseract-ocr
# macOS:
brew install poppler tesseract
# Windows (including VS Code on Windows):
# Install poppler: https://github.com/oschwartz10612/poppler-windows
# Install tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# Note: Basic PDF reading works without these
npm run build
## MCP Client Configuration
### Global Installation Configuration
If you installed globally with `npm install -g .`, you can configure your MCP clients to use the server from anywhere:
**For GitHub Copilot (VS Code):**
```json
{
"mcp.servers": {
"pdf-reader": {
"command": "pdf-mcp-server",
"cwd": "/path/to/your/pdfs"
}
}
}
For Claude Desktop:
{
"mcpServers": {
"pdf-reader": {
"command": "pdf-mcp-server",
"cwd": "/path/to/your/pdfs"
}
}
}
Local Installation Configuration
If you installed locally, use the full path:
For GitHub Copilot (VS Code):
{
"mcp.servers": {
"pdf-reader": {
"command": "node",
"args": ["/path/to/pdf-mcp-server/dist/enhanced-index.js"],
"cwd": "/path/to/your/pdfs"
}
}
}
For Claude Desktop:
Add to ~/.config/claude-desktop/config.json:
{
"mcpServers": {
"pdf-reader": {
"command": "node",
"args": ["/path/to/pdf-mcp-server/dist/enhanced-index.js"],
"cwd": "/path/to/your/pdfs"
}
}
}
Usage
Once configured, you can ask your AI assistant:
- "Read this PDF and summarize it"
- "Extract all tables from this document"
- "What images are in this PDF?"
- "Analyze the structure of this document"
Available Tools
read_pdf
Extract text content from PDF files.
{
"name": "read_pdf",
"arguments": {
"file_path": "./document.pdf",
"max_pages": 10,
"password": "optional_password"
}
}
extract_pdf_tables
Extract tables from PDF files.
{
"name": "extract_pdf_tables",
"arguments": {
"file_path": "./report.pdf",
"page_numbers": [1, 2, 3],
"password": "optional_password"
}
}
extract_pdf_images
Extract images and perform OCR.
{
"name": "extract_pdf_images",
"arguments": {
"file_path": "./document.pdf",
"ocr_enabled": true,
"password": "optional_password"
}
}
analyze_pdf_structure
Analyze PDF structure and metadata.
{
"name": "analyze_pdf_structure",
"arguments": {
"file_path": "./document.pdf",
"include_text": true,
"include_images": true,
"include_tables": true,
"password": "optional_password"
}
}
Requirements
- Node.js 16.0.0 or higher
- Optional: Python 3 with pdfplumber for advanced table extraction
- Optional: poppler-utils and tesseract-ocr for image processing and OCR
License
MIT
Installation
Quick Start (npm)
npm install -g pdf-mcp-server
From Source
git clone https://github.com/your-username/pdf-mcp-server.git
cd pdf-mcp-server
npm install
npm run build
Enhanced Features Setup
For advanced table extraction and image processing:
# Install Python dependencies for table extraction
pip install pdfplumber
# Install system tools for image extraction and OCR
# Ubuntu/Debian:
sudo apt-get install -y poppler-utils tesseract-ocr
# macOS:
brew install poppler tesseract
# Or use our convenience script:
npm run install-extras
Usage
With GitHub Copilot (VS Code)
Add to your VS Code settings.json:
{
"mcp.servers": {
"pdf-reader": {
"command": "pdf-mcp-server",
"cwd": "/path/to/your/pdfs"
}
}
}
With Claude Desktop
Add to your Claude Desktop config (~/.config/claude-desktop/config.json):
{
"mcpServers": {
"pdf-reader": {
"command": "pdf-mcp-server",
"cwd": "/path/to/your/pdfs"
}
}
}
Direct Usage
# Start the MCP server
pdf-mcp-server
# Or run locally
node dist/enhanced-index.js
Available Tools
1. read_pdf
Extract text content from PDF files with password support and automatic OCR.
{
"name": "read_pdf",
"arguments": {
"file_path": "./document.pdf",
"max_pages": 5,
"password": "optional_password"
}
}
2. extract_pdf_tables
Extract structured table data from PDF files with enhanced detection.
{
"name": "extract_pdf_tables",
"arguments": {
"file_path": "./report.pdf",
"page_numbers": [1, 2, 3],
"password": "optional_password"
}
}
3. extract_pdf_images
Extract images and optionally perform OCR on them.
{
"name": "extract_pdf_images",
"arguments": {
"file_path": "./diagram.pdf",
"ocr_enabled": true,
"password": "optional_password"
}
}
4. analyze_pdf_structure
Comprehensive document structure analysis with configurable options.
{
"name": "analyze_pdf_structure",
"arguments": {
"file_path": "./document.pdf",
"include_text": true,
"include_images": true,
"include_tables": true,
"password": "optional_password"
}
}
Example Prompts
Once configured, ask your AI assistant:
- "Read this PDF and summarize the main points"
- "Extract all tables from this financial report"
- "What images are in this PDF and what do they contain?"
- "Analyze the structure of this research paper"
- "Find all references to 'machine learning' in these PDFs"
- "Read this password-protected PDF using password: mypassword"
What's New in v2.0
Enhanced Password Support: All tools now support password-protected PDFs through an optional password parameter.
Automatic OCR Fallback: When no text is found in a PDF (common with scanned documents), the server automatically attempts OCR extraction using tesseract.
Advanced Table Detection: Improved text-based table detection algorithms with better pattern recognition for currency, percentages, and structured data.
Memory Optimization: Large PDF files (>50MB) are now processed with memory optimization techniques to prevent crashes.
Enhanced Error Handling: Better error messages and graceful degradation when optional dependencies are missing.
Dual Processing Methods: Tables can be extracted using both enhanced text analysis and pdfplumber (when available) for maximum compatibility.
Architecture
PDF MCP Server v2.0
├── Text Extraction (pdf-parse + password support)
├── Table Detection (enhanced patterns + pdfplumber)
├── Image Processing (poppler-utils + tesseract OCR)
├── Document Analysis (metadata + structure + optimization)
└── MCP Protocol Interface (@modelcontextprotocol/sdk)
Development
Project Structure
src/
├── index.ts # Basic PDF reader (legacy)
├── enhanced-index.ts # Full-featured server v2.0
└── test.ts # Test utilities
dist/ # Compiled JavaScript
test-enhanced.js # Enhanced server test
ENHANCEMENT_COMPLETE.md # v2.0 upgrade documentation
README.md
package.json
tsconfig.json
Building
npm run build
Development Mode
npm run dev # Watch mode with auto-rebuild
Testing
npm test
# Test enhanced server
node test-enhanced.js
Requirements
- Node.js: 16.0.0 or higher
- Operating System: Linux, macOS, or Windows with WSL
Optional Dependencies
- Python 3 with pdfplumber (for advanced table extraction)
- poppler-utils (for image extraction)
- tesseract-ocr (for OCR capabilities)
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the file for details.
Acknowledgments
- Built with @modelcontextprotocol/sdk
- PDF parsing powered by pdf-parse
- Enhanced table extraction via pdfplumber
- OCR capabilities through Tesseract
Issues & Support
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- Documentation:
Made for the MCP and AI assistant community