paddleocr-mcp

# PaddleOCR MCP Server [](LICENSE) [](https://github.com/PaddlePaddle/PaddleOCR/blob/main/LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) A locally running PaddleOCR MCP Server, supporting dual models + automatic routing + GPU automatic detection. ## ⚡ One-Click Installation (Copy to Your Agent) > Directly provide the following instructions to any AI Agent, and it will automatically complete the installation and configuration. ``` Please help me install paddleocr-mcp (https://github.com/Nicvank/paddleocr-mcp), which is a local OCR MCP service supporting PP-OCRv6 (fast text extraction) and VL-1.6 (document structure parsing), automatic routing, and automatic GPU/CPU detection. Installation steps: 1. git clone https://github.com/Nicvank/paddleocr-mcp.git ~/paddleocr-mcp (If cloning fails, try the ghproxy mirror: git clone https://ghproxy.net/https://github.com/Nicvank/paddleocr-mcp.git ~/paddleocr-mcp) 2. Check the Python version (required: 3.10-3.12, not supporting 3.13+), and install Python 3.12 if necessary 3. cd ~/paddleocr-mcp && python -m venv .venv && .venv/bin/pip install -e . (The initial installation requires downloading ~300MB of dependencies, please be patient) 4. Add the MCP server configuration to my Agent client: command: ~/paddleocr-mcp/.venv/bin/python (must use the venv Python, not the system Python) args: ["~/paddleocr-mcp/paddleocr_mcp_server.py"] timeout: 600 (VL-1.6 is slower on CPU, and requires downloading ~300MB of models initially) 5. Read ~/paddleocr-mcp/skill/SKILL.md and load it according to your platform 6. Restart and tell the user: "Please send me a picture to test if OCR is working normally" If any step fails, report the error and fix it. After completion, tell me the result. ``` ## Features | Feature | Description | |------|------| | **Dual Models** | PP-OCRv6 (fast) + VL-1.6 (document structured) | | **Automatic Routing** | Automatically select the best model based on input | | **GPU Automatic Detection** | Detect CUDA availability and automatically switch between CPU/GPU | | **MCP Protocol** | Standard Model Context Protocol, compatible with all MCP clients | | **Hermes Integration** | One-line configuration to access Hermes Agent | ## Model Comparison > ⚡ The following speeds are based on **CPU hard calculation** (Xeon E5-2698B v3). Using GPU (e.g., NVIDIA P106/GTX 1060) can improve performance by **10-25 times**. | Model | Purpose | Speed (CPU) | Speed (GPU estimated) | Best Scenario | |------|------|-----------|----------------|---------| | **PP-OCRv6** | Fast Text Extraction | ~12-18s | ~1-2s | Screenshots, photos, invoices, receipts | | **VL-1.6** | Document Structure Parsing | 30-120s | ~5-15s | Complex layouts, tables, multi-column documents, PDFs | **Hardware Recommendations:** - **Pure CPU**: Any x86_64 processor can run, suitable for low-frequency usage - **GPU Acceleration**: NVIDIA CUDA graphics card (GTX 1060 / P106 6GB or above), memory ≥ 6GB, suitable for high-frequency or real-time scenarios > ⚠️ **When using VL-1.6 for the first time**, the model file (~300MB) will be automatically downloaded from ModelScope, requiring an additional 1-5 minutes. The model cache is stored in `~/.paddlex/official_models/`, and subsequent calls do not require repeated downloads. ## Installation ### Prerequisites - Python 3.10 ~ 3.12 (not supporting 3.13+) - PaddlePaddle 3.2+ (CPU or GPU version) - PaddleOCR 3.7+ ### Installation Steps ```bash # 1. Clone the repository git clone https://github.com/Nicvank/paddleocr-mcp.git cd paddleocr-mcp # 2. Create a virtual environment and install dependencies python -m venv .venv .venv/bin/pip install -e . # ⚠️ The initial installation requires downloading ~300MB of dependencies (paddlepaddle 195MB + opencv 69MB), # please be patient or use uv acceleration: uv pip install -e . # For users in mainland China, if pip download times out, use the Tsinghua mirror: # .venv/bin/pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple # For users in mainland China, if git clone fails, try the mirror: # git clone https://ghproxy.net/https://github.com/Nicvank/paddleocr-mcp.git ``` ### GPU Support (Optional) ```bash # Install the GPU version of PaddlePaddle pip install paddlepaddle-gpu==3.2.1 # Verify GPU availability python -c "import paddle; print(paddle.is_compiled_with_cuda())" ``` ## Usage ### Direct Run ```bash python paddleocr_mcp_server.py ``` ### Hermes Agent Integration > ⚠️ **After installing the MCP server, you must restart the Hermes Gateway to load the new tool.** #### Gateway Mode (systemd daemon) Add the following to the **global configuration** `~/.hermes/config.yaml`: ```yaml mcp_servers: paddleocr: command: /path/to/paddleocr-mcp/.venv/bin/python args: - /path/to/paddleocr-mcp/paddleocr_mcp_server.py timeout: 600 connect_timeout: 120 ``` > ⚠️ Note: `args` must be in **YAML list format** (`- item`), do not write as a string `"[\"item\"]"`. > ⚠️ In Gateway mode, MCP configuration is read from `$HERMES_HOME/config.yaml` (i.e., `~/.hermes/config.yaml`), not at the profile level. #### CLI Mode Add the following to `~/.hermes/profiles/<your-profile>/config.yaml` (same configuration). Restart Hermes to make it available. ### Other MCP Clients Any client supporting MCP stdio transmission can connect: ```json // Claude Desktop (claude_desktop_config.json) { "mcpServers": { "paddleocr": { "command": "python", "args": ["/path/to/paddleocr_mcp_server.py"] } } } ``` ## 🤖 Agent Skill This project includes an **Agent Skill** ([skill/SKILL.md](skill/SKILL.md)) that informs the AI Agent when and how to call the OCR tool. ### What is an Agent Skill? A Skill is a structured document that tells the Agent: - **When** to call OCR (trigger conditions) - **Which tool** to use (ocr_image vs parse_document vs smart_ocr) - **How** to use it (parameters, return values, error handling) - **Decision tree** (automatically select the best model based on the scenario) ### Install to Hermes ```bash # Gateway mode: copy to the global skills directory cp -r skill/ ~/.hermes/skills/paddleocr-mcp/ # CLI mode: copy to the profile's skills directory cp -r skill/ ~/.hermes/profiles/<your-profile>/skills/media/paddleocr-mcp/ # Alternatively, create a symbolic link (recommended for easy updates) ln -s /path/to/paddleocr-mcp/skill ~/.hermes/skills/paddleocr-mcp ``` The Agent will automatically load this Skill in the following situations: - The user sends an image and requests text extraction - The user requests document parsing - Any task involving OCR ### Skill Trigger Conditions The Agent will load the Skill when the following keywords appear: ``` Extract text, OCR, image text, document parsing, PDF parsing, screenshot recognition, table extraction, image recognition, read image ``` ### Using without Skill Even without installing the Skill, as long as the MCP Server is configured, the Agent can directly call the tool: ``` User: Help me see what this screenshot says Agent: Call mcp_paddleocr_ocr_image (automatic selection) ``` The Skill's role is to make the Agent **smarter in choosing** and **better in handling results**. ## MCP Tools ### `ocr_image` — Fast OCR PP-OCRv6 model, suitable for simple text extraction. ```json { "image_path": "/path/to/image.png", "language": "ch" } ``` **Parameters:** - `image_path` (required): image file path - `language` (optional): language code, default `"ch"` (Chinese-English) **Supported Languages:** `ch` (Chinese-English), `en`, `japan`, `korean`, `fr`, `german`, etc. ### `parse_document` — Document Parsing VL-1.6 visual language model, suitable for complex document structuring. ```json { "image_path": "/path/to/document.pdf" } ``` **Returns:** Markdown format document structure ### `smart_ocr` — Automatic Routing Automatically select the best model based on input. ```json { "image_path": "/path/to/file", "language": "ch", "force_model": "ocr" } ``` **Routing Rules:** - PDF file → VL-1.6 - Image > 2000px → VL-1.6 - Others → PP-OCRv6 - `force_model`: `"ocr"` or `"vl"` to force specification ## Environment Variables | Variable | Default Value | Description | |------|--------|------| | `PADDLEOCR_DEVICE` | `auto` | Force device: `cpu` or `gpu` | | `PADDLEOCR_VL_TIMEOUT` | `300` | VL-1.6 timeout (seconds) | ## CPU Compatibility (OneDNN) On some CPUs (especially older or non-Intel architectures), PaddlePaddle's OneDNN (MKL-DNN) backend conflicts with the PIR inference engine, causing crashes: ``` NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support ``` **The server has built-in automatic handling** (`enable_mkldnn=False`), and no manual intervention is required in most cases. If issues still occur: 1. Set the environment variable: `export FLAGS_use_mkldnn=0` 2. Or add to the MCP configuration: ```yaml mcp_servers: paddleocr: command: /path/to/python args: - /path/to/paddleocr_mcp_server.py env: FLAGS_use_mkldnn: "0" timeout: 600 ``` ## Diagnostic Tool Run the diagnostic check after installation: ```bash .venv/bin/python paddleocr_mcp_server.py doctor ``` Checks: Python version, dependency integrity, model loading, OneDNN compatibility, GPU detection, VL-1.6 model cache. ## Testing ```bash # Install test dependencies pip install pytest # Run tests python -m pytest tests/ -v # Quick functional test python test_quick.py # MCP protocol test python test_mcp.py ``` ## Project Structure ``` paddleocr-mcp/ ├── paddleocr_mcp_server.py # MCP Server main program ├── pyproject.toml # Project configuration ├── skill/ │ └── SKILL.md # Agent Skill documentation ├── tests/ │ └── test_tools.py # Unit tests ├── test_quick.py # Quick functional test ├── test_mcp.py # MCP protocol test ├── LICENSE # MIT License ├── .gitignore └── README.md ``` ## License This project uses the [MIT License](LICENSE). **Dependency Licenses:** - [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) — Apache License 2.0 - [PaddleOCR-VL-1.6 model](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6) — Apache License 2.0 - [PaddlePaddle](https://github.com/PaddlePaddle/PaddlePaddle) — Apache License 2.0 - [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — MIT License Apache 2.0 is a permissive license, fully compatible with MIT. No additional license obligations are required to use this project. ## Acknowledgements - [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) — Baidu PaddlePaddle OCR toolkit - [Model Context Protocol](https://modelcontextprotocol.io) — MCP protocol standard - [trotsky1997/PaddleOCR-MCP](https://github.com/trotsky1997/PaddleOCR-MCP) — Original MCP implementation reference