Content
# DeepSeek PDF Reader MCP Server v5.0.0
[](https://github.com/FLT1milize/deepseek-pdf-reader)
[](https://www.python.org/)
[](LICENSE)
[](test_server.py)
[](https://github.com/modelcontextprotocol/python-sdk)
MCP Server providing comprehensive PDF processing capabilities: text extraction (auto OCR), keyword search (supporting regex), table extraction (three paths), and page preview (Base64 PNG).
**v5.0.0 Major Update**: Reconstructed based on the official `mcp` Python SDK, 12-file modular architecture, supporting SDK mode + built-in JSON-RPC compatible mode dual engines.
---
## 🆕 v5.0.0 vs v4.0.0
| | v4.0.0 | v5.0.0 |
|---|---|---|
| Architecture | Monolithic 504 lines | 12-file modular (~650 lines) |
| MCP Protocol | Handwritten JSON-RPC | Official SDK + dual-mode engine |
| inputSchema | Manual JSON Schema maintenance | SDK mode auto-generation / compatible mode predefined |
| Lifecycle | Incomplete | `lifespan` context manager |
| Logging | stderr invisible | SDK mode pushes to client via `ctx.info()` |
| Packaging | requirements.txt | pyproject.toml (PEP 621) |
## Feature Overview
| Tool | Description |
|------|------|
| `read_pdf` | Read PDF text, supporting `text` / `json` / `markdown` output formats, auto OCR for scanned documents |
| `list_pdf_info` | Get PDF metadata: page count, file size, encryption status, text layer presence, OCR status, Tesseract language pack |
| `search_pdf` | Search keywords, supporting regex, returns page numbers, hit counts, and context extracts |
| `extract_tables` | Three-path table extraction strategy: PyMuPDF built-in detection (bordered) → block/line structured parsing → TSV coordinate clustering (borderless fallback) |
| `preview_page` | Render specified page as PNG image (Base64 encoded), directly displayable in chat interfaces |
## System Requirements
- **Python** 3.10+
- **Tesseract OCR** (optional, for scanned PDF text recognition):
| Platform | Installation Command |
|------|----------|
| Windows | Download and install [Tesseract-OCR](https://github.com/UB-Mannheim/tesseract/wiki), select Chinese language pack during installation |
| macOS | `brew install tesseract tesseract-lang` |
| Ubuntu/Debian | `sudo apt install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng` |
| Arch Linux | `sudo pacman -S tesseract tesseract-data-eng tesseract-data-chi_sim` |
## Installation
```bash
# Clone repository
git clone https://github.com/FLT1milize/deepseek-pdf-reader.git
cd deepseek-pdf-reader
# Install Python dependencies
pip install -r requirements.txt
```
## Run Tests
```bash
python test_server.py
```
Expected output: `[OK] All 30 tests passed!`
## Configure in Cline
Edit Cline's MCP configuration file, add the following entry:
```json
{
"mcpServers": {
"deepseek-pdf-reader": {
"command": "python",
"args": ["path/to/deepseek-pdf-reader/server.py"],
"env": {
"TESSERACT_CMD": "C:/Program Files/Tesseract-OCR/tesseract.exe"
}
}
}
}
```
> **Tip**: `TESSERACT_CMD` is optional; if left empty, the server will automatically search for common installation paths. You can also specify the language pack path via environment variable `TESSDATA_PREFIX`.
## Configuration Options
| Environment Variable | Description | Default Value |
|----------|------|--------|
| `TESSERACT_CMD` | Tesseract executable path | Auto search |
| `TESSDATA_PREFIX` | tessdata language pack directory | Auto search |
## Architecture Description
```
deepseek-pdf-reader/
├── server.py # Entry: SDK mode + built-in JSON-RPC compatible engine
├── config.py # Global settings (Settings dataclass)
├── ocr.py # Tesseract 5-path auto-discovery + OCR invocation
├── doc.py # PDFDoc class (thread-safe cache + LRU) + document pool
├── table.py # TSV coordinates → table structure (borderless table detection)
├── format.py # Formatting tools (text/json/markdown output)
├── tools/
│ ├── read_pdf.py # read_pdf tool
│ ├── list_info.py # list_pdf_info tool
│ ├── search_pdf.py # search_pdf tool
│ ├── extract_tables.py # extract_tables tool
│ └── preview_page.py # preview_page tool
├── pyproject.toml # PEP 621 project configuration
└── test_server.py # 30 unit tests
```
**Dual-Engine Design**: Prioritize using the official `mcp` SDK (auto inputSchema, lifespan, logging push); if the SDK is not installed, automatically fall back to the built-in JSON-RPC 2.0 engine, available with zero additional dependencies.
Core dependencies: [PyMuPDF](https://pymupdf.readthedocs.io/) (fitz) + [mcp](https://github.com/modelcontextprotocol/python-sdk) (optional), OCR via subprocess invocation of Tesseract CLI.
## License
MIT · See [LICENSE](LICENSE) for details.
