PaddleOCR MCP server: OCR tools for Claude and other agents

Pick an inference mode first#

The MCP server is a thin adapter. It always runs on your machine, but the OCR itself runs wherever PADDLEOCR_MCP_PPOCR_SOURCE points. That choice decides what you install, what you pay and where your files go.¹

The docs recommend local for "offline use and scenarios with strict data privacy requirements". They recommend the Official API for "quickly trying out features". Self-hosted gives you "serving advantages and high flexibility", but "only the basic serving solution is supported", not Triton-based high-stability serving.¹

The three tools#

Each server process runs one model and exposes one tool. The tool depends on the model. To give Claude plain OCR and document parsing, register two servers under different names.¹³

Every tool takes the same arguments. This is the schema our client received from 0.8.5:³⁴

In simple mode the ocr tool returns the text followed by a summary line. On our receipt it ended with Confidence: 99.3% | 27 text lines.⁴

Install#

pip install -U paddleocr-mcp

# Install the CPU PaddlePaddle framework in addition to local:
pip install "paddleocr-mcp[local-cpu]"

# Install document-parsing dependencies for local inference (inference engine not included):
pip install "paddleocr-mcp[local]"

git clone https://github.com/PaddlePaddle/PaddleOCR.git
pip install -e mcp_server

Check it with paddleocr_mcp --help. The base package already depends on paddleocr>=3.7.0, so the three API modes need nothing else. In our fresh venv the API-mode install took 73 seconds. [local] adds paddleocr[doc-parser]. [local-cpu] also adds paddlepaddle>=3.2.1. The docs "strongly" recommend a separate virtual environment.¹²⁴

For a GPU, use [local] and install paddlepaddle-gpu yourself, as on our install page. The local-cpu pin allows the PyPI 3.3.x builds. We saw those crash PaddleOCR 3.7.0 CPU inference in our tests, so if local OCR fails with ConvertPirAttribute2RuntimeAttribute, see troubleshooting.

Claude Desktop configuration#

Open claude_desktop_config.json, add one of the blocks below, and restart Claude Desktop:¹

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

The configs are verbatim from the official docs. Their examples use PP-OCRv5; change it to PP-OCRv6 (the server default) or to any model in the table above.¹

{
  "mcpServers": {
    "paddleocr": {
      "command": "paddleocr_mcp",
      "args": [],
      "env": {
        "PADDLEOCR_MCP_MODEL": "PP-OCRv5",
        "PADDLEOCR_MCP_PPOCR_SOURCE": "aistudio",
        "PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "paddleocr": {
      "command": "paddleocr_mcp",
      "args": [],
      "env": {
        "PADDLEOCR_MCP_MODEL": "PP-OCRv5",
        "PADDLEOCR_MCP_PPOCR_SOURCE": "local"
      }
    }
  }
}

{
  "mcpServers": {
    "paddleocr": {
      "command": "paddleocr_mcp",
      "args": [],
      "env": {
        "PADDLEOCR_MCP_MODEL": "PaddleOCR-VL",
        "PADDLEOCR_MCP_PPOCR_SOURCE": "qianfan",
        "PADDLEOCR_MCP_QIANFAN_API_KEY": "<your-api-key>"
      }
    }
  }
}

{
  "mcpServers": {
    "paddleocr": {
      "command": "paddleocr_mcp",
      "args": [],
      "env": {
        "PADDLEOCR_MCP_MODEL": "PP-OCRv5",
        "PADDLEOCR_MCP_PPOCR_SOURCE": "self_hosted",
        "PADDLEOCR_MCP_SELF_HOSTED_BASE_URL": "<your-server-url>"
      }
    }
  }
}

• Self-hosted URL: give the base URL only, e.g. http://127.0.0.1:8080, "without path suffixes such as /ocr or /layout-parsing". The MCP server adds the right suffix for the pipeline.¹
• Command not found? If paddleocr_mcp isn't on the PATH Claude Desktop sees (common with virtualenvs), set command to the absolute path, e.g. /home/you/.venvs/ocr/bin/paddleocr_mcp.¹
• Debug output: add "args": ["--verbose"].¹

Without installing: uvx#

With uv installed, uvx fetches and runs the package on demand. The env vars work the same way. This is the official local-CPU example:¹

{
  "mcpServers": {
   "paddleocr": {
    "command": "uvx",
    "args": [
      "--from",
      "paddleocr-mcp[local-cpu]",
      "paddleocr_mcp"
    ],
    "env": {
      "PADDLEOCR_MCP_MODEL": "PP-OCRv5",
      "PADDLEOCR_MCP_PPOCR_SOURCE": "local"
    }
   }
  }
}

For the API modes, use "paddleocr-mcp" without the extra.¹

Claude Code, Cursor and other MCP hosts#

The official doc covers Claude Desktop and says the steps "are also applicable to other MCP hosts with minor adjustments". Any host that accepts the standard mcpServers JSON (command, args, env) can take the blocks above as they are.¹ For Claude Code, the CLI adds a stdio server with -e for each variable. The commands below are derived by us from claude mcp add --help:⁵

# stdio: Claude Code starts paddleocr_mcp itself
claude mcp add paddleocr \
  -e PADDLEOCR_MCP_MODEL=PP-OCRv6 \
  -e PADDLEOCR_MCP_PPOCR_SOURCE=aistudio \
  -e PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=your-token \
  -- paddleocr_mcp

# or run one shared server over Streamable HTTP and point clients at it
paddleocr_mcp --model PP-OCRv6 --ppocr_source local --http   # listens on 127.0.0.1:8000
claude mcp add --transport http paddleocr http://127.0.0.1:8000/mcp

We checked the HTTP endpoint. paddleocr_mcp --http answered an MCP initialize request on http://127.0.0.1:8000/mcp and identified itself as "PaddleOCR PP-OCRv6 MCP server". --host and --port are only accepted together with --http. Without it the server exits with "Host and port arguments are only valid when using HTTP transport".³⁴

The official demos also show the server in VS Code alongside the filesystem MCP server, and in Claude Desktop with the Notion MCP server.¹

All environment variables and flags#

Every setting can be an environment variable (for the host config) or a CLI flag (for the command line). Note the mix of dashes and underscores in the flag names. Copy them exactly.¹

Official command-line examples:¹

# PP-OCRv5 + Official API + stdio
PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=xxxxxx paddleocr_mcp --model PP-OCRv5 --ppocr_source aistudio

# PP-StructureV3 + Local Inference + stdio
paddleocr_mcp --model PP-StructureV3 --ppocr_source local

# OCR + Self-hosted API + Streamable HTTP
paddleocr_mcp --model PP-OCRv5 --ppocr_source self_hosted --self-hosted-base-url http://127.0.0.1:8080 --http

Local mode: making it fast enough#

Local mode loads a full PaddleOCR pipeline inside the MCP process. Plain OCR is fine on a CPU: PP-OCRv6 tiers run in 0.3–2.9 s per page in our benchmark. Document parsing is heavier. The docs suggest exporting a slimmer pipeline config and pointing PADDLEOCR_MCP_PIPELINE_CONFIG at it. This is their example for PP-StructureV3:¹

from paddleocr import PPStructureV3

pipeline = PPStructureV3(
    use_doc_orientation_classify=False, # Disable document image orientation classification
    use_doc_unwarping=False,            # Disable text image unwarping
    use_textline_orientation=False,     # Disable text line orientation classification
    use_formula_recognition=False,      # Disable formula recognition
    use_seal_recognition=False,         # Disable seal text recognition
    use_table_recognition=False,        # Disable table recognition
    use_chart_recognition=False,        # Disable chart parsing
    # Use lightweight models
    text_detection_model_name="PP-OCRv5_mobile_det",
    text_recognition_model_name="PP-OCRv5_mobile_rec",
    layout_detection_model_name="PP-DocLayout-S",
)

# The configuration file is saved to `PP-StructureV3.yaml`
pipeline.export_paddlex_config_to_yaml("PP-StructureV3.yaml")

For the PaddleOCR-VL models the docs are blunt: "CPU inference is not recommended." Use a GPU, or switch to self_hosted or an API mode for those.¹

What happened when we wired it to a self-hosted server#

We installed 0.8.5 in a clean venv. We pointed it at PaddleX basic serving running PP-OCRv6 small in Docker (setup in our serving guide) and called the ocr tool over stdio with an MCP client.⁴

• First call failed. Passing only input_data (an absolute .jpg path), the client got just Error calling tool 'ocr'. With --verbose, the server log showed HTTP 422 (self_hosted/ocr). The MCP server had sent the image as Base64 without a file type, and PaddleX rejects that with "File type cannot be determined". This is the same 422 we hit calling the server directly.
• Adding "file_type": "image" fixed it. All 27 lines came back. Hosts normally let the model fill in arguments, and the tool description does tell it to set file_type for HTTP backends. If you see failures, tell the assistant to "use file_type image" (or pdf).
• Error details are hidden from the host. The server is created with mask_error_details=True, so a relative path, a bad token or a 422 all look the same to the client. Run with "args": ["--verbose"] and read the server's stderr log.³

Troubleshooting#

The docs also list "cannot process PDF document inputs that are Base64 encoded" as a local-mode limitation. The 0.8.5 source now writes Base64 PDFs to a temporary file in local mode, so this may be outdated. We didn't test it. Passing a path is the safe choice.¹³

Privacy by mode#

• local: files never leave the machine. Model weights download once (from Hugging Face by default) and are cached in ~/.paddlex.
• self_hosted: files go only to the server you name. With http:// on a network, they travel unencrypted, so use HTTPS or keep it on localhost.
• aistudio / qianfan: files are uploaded to Baidu's services and counted against your quota (3,000 pages per model per day on AI Studio).⁸ Don't use these for documents you can't share with a third party.
• In every mode, the OCR text is sent to your LLM provider as a tool result, because that's the point. Local OCR keeps the image private, but not the words in it.

Related: Agent Skills and the LangChain loader#

PaddleOCR Agent Skills#

Two official skills, paddleocr-text-recognition and paddleocr-doc-parsing, for Skills-capable apps such as Claude Code. Both call the hosted API through the paddleocr api CLI. They need Python 3.9+, paddleocr>=3.7.0 and PADDLEOCR_ACCESS_TOKEN.⁶

npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y
npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y

For Claude Code, the docs put the token in .claude/settings.local.json:

{
  "env": {
    "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>"
  }
}

The npm package paddleocr-skills is not referenced by the official docs.

LangChain: langchain-paddleocr#

PaddleOCRVLLoader loads PDFs and images as LangChain Documents using the PaddleOCR-VL models on the hosted API. It is version 0.2.2 and needs Python 3.10+.⁷

from langchain_paddleocr import PaddleOCRVLLoader
from pydantic import SecretStr

loader = PaddleOCRVLLoader(
    file_path="path/to/document.pdf",
    base_url="your-api-endpoint",
    model="PaddleOCR-VL-1.5",
    access_token=SecretStr("your-access-token")  # Optional if using environment variable `PADDLEOCR_ACCESS_TOKEN`
)

docs = loader.load()

The default base_url in the source is https://paddleocr.aistudio-app.com.

Want to OCR without any agent? See the serving & API guide, the Python quick start, or try PP-OCRv6 in our browser tool.

Questions#