# PDF MCP Server
An MCP server that enables reading PDF file contents, allowing PDF documents to be used as a knowledge base for LLMs.
## Features
- **High-Quality Extraction**: Uses [marker-pdf](https://github.com/VikParuchuri/marker) (via a Python backend) to extract text with layout awareness and high-fidelity LaTeX equation recognition.
- **Robust Fallback**: Automatically switches to a Node.js-based parser (`pdf-parse`) if the Python environment is unavailable or fails, ensuring extraction always succeeds (albeit with lower formatting quality).
- **Smart Filtering**: Supports page range extraction to process only relevant sections of large documents.
## Installation
### Prerequisites
- **Node.js** (v18+)
- **Python** (v3.10+) and `pip` (for high-quality extraction)
### Setup
1. **Install Node.js dependencies:**
```bash
npm install
```
2. **Install Python dependencies (Recommended):**
To enable high-quality extraction (especially for scientific papers with math), install the Python dependencies.
```bash
# Create or activate a virtual environment if desired
python3 -m pip install -r python/requirements.txt
```
> **Note:** The first time you run the tool with the Python backend, it will download necessary AI models (OCR, layout analysis, etc.) to a local cache. **This download is approximately 3.3GB.** Ensure you have a stable internet connection.
3. **Build the server:**
```bash
npm run build
```
## Usage
### Configuration for Claude/MCP Clients
Add this to your MCP settings configuration:
```json
{
"mcpServers": {
"pdf-reader": {
"command": "node",
"args": ["/absolute/path/to/mcpPdf/dist/index.js"],
"env": {
// Optional: Override where python is found if not in venv or path
// "PYTHON_PATH": "/path/to/python"
}
}
}
}
```
### Tool: `read_pdf`
Reads and extracts text content from a PDF file.
**Inputs:**
- `path` (string): Absolute path to the PDF file.
- `start_page` (number, optional): Starting page number (1-based).
- `end_page` (number, optional): Ending page number (1-based).
**How it works:**
1. **Attempt 1 (Python/Marker)**: The server tries to run the internal `convert.py` script.
- If successfully configured, this loads the `marker` models from the local cache (`.cache` directory in the project).
- It accurately converts equations to LaTeX and preserves document structure.
2. **Attempt 2 (Fallback)**: If the Python script fails (e.g., missing dependencies, runtime error), the server catches the error and uses `pdf-parse` (a native Node.js library).
- This extracts raw text. Equations may appear as linearized text, and layout may be less preserved.
## Troubleshooting
- **Permission Errors**: The project is configured to use a local `.cache` directory for models to avoid system permission issues. If you encounter errors, ensure the project directory is writable.
- **Slow Performance**: The high-quality extraction uses deep learning models. It can be slow on large documents without a GPU. Use the `start_page` and `end_page` arguments to extract only what you need.
