Content
# Tool List
Chart-OCR-mcp is a chart recognition tool based on PaddleOCR, supporting extraction of chart/table regions from single image or PowerPoint files, and outputting structured JSON results.
The project currently provides three usage methods:
- CLI command-line tool: suitable for local batch processing and script invocation.
- FastAPI Web service: suitable for uploading images or PPTs and viewing results in the browser.
- MCP local tool: suitable for Claude, Codex, and other agents to directly call through stdio.
## Features
- Single chart image recognition: use `PP-Chart2Table` to parse charts and output table text.
- PPT chart recognition: automatically render PPT/PPTX into images, detect chart/table/graphic regions, crop, and then recognize in batch.
- Detection mode: PPT can only render and detect candidate regions, without executing complete OCR.
- Web API: provide image OCR, PPT OCR, example images, and generated file access interfaces.
- MCP Server: expose `health_check`, `ocr_chart_image`, and `ocr_ppt_charts` tools for direct agent invocation.
- GPU default configuration: use `PADDLE_OCR_DEVICE=gpu:0` by default, can also switch devices in `.env`.
## Runtime Environment
Recommended environment:
- Windows 10/11
- Python `>=3.10,<3.13`
- uv
- NVIDIA GPU + CUDA 12.6 related environment
- Microsoft PowerPoint, PPT rendering requires local PowerPoint COM
Current dependencies default to install GPU version:
```toml
paddlepaddle-gpu==3.3.0
```
If you want to switch to CPU, replace `paddlepaddle-gpu` with PaddlePaddle CPU version in dependencies, and change device to:
```env
PADDLE_OCR_DEVICE=cpu
```
## Installation
Execute in project directory:
```powershell
cd C:\path\to\chart-ocr-mcp
uv sync
```
First run will download PaddleOCR models to local cache directory, time depends on network and model cache status.
## Environment Configuration
Project reads `.env`:
```env
PADDLE_OCR_DEVICE=gpu:0
```
Common values:
- `gpu:0`: use first GPU
- `cpu`: use CPU
Do not commit `.env` to GitHub.
## CLI Usage
### Recognize Single Chart Image
Output to file:
```powershell
uv run chart-ocr input\1.png --out result.json --pretty
```
Directly output in terminal:
```powershell
uv run chart-ocr input\1.png --pretty
```
### Recognize PPT Charts
Complete recognition:
```powershell
uv run ppt-chart-ocr input\output.pptx --out outputs\ppt_result.json --pretty
```
Only detect and crop candidate chart regions, without executing chart OCR:
```powershell
uv run ppt-chart-ocr input\output.pptx --detect-only --work-dir outputs\ppt_detect --out outputs\ppt_detect.json --pretty
```
Common parameters:
- `--work-dir`: save rendered slides and cropped images directory
- `--detect-only`: only do PPT rendering, layout detection, and cropping
- `--render-width` / `--render-height`: control PPT rendering resolution
- `--labels`: specify retained layout types, default `chart,table,figure`
- `--min-score`: candidate region minimum confidence
- `--min-area-ratio`: candidate region minimum area ratio
## Web Service
Start service:
```powershell
uv run python server.py
```
Default address:
```text
http://127.0.0.1:8000
```
Main interfaces:
- `POST /api/ocr`: upload image and execute chart OCR
- `POST /api/ppt/ocr`: upload `.ppt` or `.pptx` and execute PPT chart recognition
- `GET /api/demo`: read local `result.json` example result
- `GET /api/sample-images`: list example images under `input/`
- `GET /api/generated/{root_name}/{path}`: access generated image files
PPT interface supports `detect_only` parameter:
```text
POST /api/ppt/ocr?detect_only=true
```
## MCP Agent Tool
This project has been encapsulated as a local stdio MCP Server, agents can directly invoke project capabilities without detouring through Web API.
MCP Server name:
```text
chart-ocr-mcp
```
Start command:
```powershell
uv --directory C:\path\to\chart-ocr-mcp run chart-ocr-mcp
```
Agent configuration example:
```json
{
"mcpServers": {
"chart-ocr-mcp": {
"command": "uv",
"args": ["--directory", "C:\\path\\to\\chart-ocr-mcp", "run", "chart-ocr-mcp"]
}
}
}
```
### MCP Tool List
#### `health_check`
Lightweight health check, without loading OCR large models.
Returns:
- Server name and version
- Python runtime environment
- Current device configuration
- `paddleocr` importability
- `mcp` importability
- PPT rendering dependency description
#### `ocr_chart_image`
Recognize local image file.
Parameters:
```json
{
"image_path": "C:\\path\\to\\chart-ocr-mcp\\input\\1.png"
}
```
Returns:
```json
{
"success": true,
"source": "C:\\path\\to\\image.png",
"device": "gpu:0",
"data": {},
"error": null
}
```
Supported suffixes:
```text
.png, .jpg, .jpeg, .bmp, .webp, .tif, .tiff
```
#### `ocr_ppt_charts`
Recognize local PPT/PPTX file.
Parameters:
```json
{
"ppt_path": "C:\\path\\to\\chart-ocr-mcp\\input\\output.pptx",
"detect_only": true,
"work_dir": "C:\\path\\to\\chart-ocr-mcp\\outputs\\mcp_test"
}
```
Field description:
- `ppt_path`: PPT/PPTX file path
- `detect_only`: if `true`, only detect and crop chart regions, without executing Chart OCR
- `work_dir`: optional, save rendered slides and cropped images; if not passed, default write to `outputs/mcp/<request_id>/`
Returns:
- PPT source path
- Working directory
- Rendered size and page count
- Detection model information
- Chart candidate count
- Per-page candidate regions
- Cropped image paths
- OCR results, if not `detect_only`
## MCP Availability Test
Execute in PowerShell:
```powershell
cd C:\path\to\chart-ocr-mcp
@'
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
params = StdioServerParameters(
command="uv",
args=["--directory", r"C:\path\to\chart-ocr-mcp", "run", "chart-ocr-mcp"],
)
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([tool.name for tool in tools.tools])
asyncio.run(main())
'@ | .\.venv\Scripts\python.exe -
```
Expected output:
```text
['health_check', 'ocr_chart_image', 'ocr_ppt_charts']
```
## Output Directory
Common output locations:
- `outputs/`: CLI, MCP, and test outputs
- `uploads/`: Web upload and processing files
- `input/`: example images and PPTs
Do not commit runtime outputs to GitHub.
## Project Structure
```text
.
├── input/ # example input files
├── outputs/ # runtime output directory
├── static/ # Web frontend static files
├── uploads/ # Web upload and intermediate files
├── src/chart_ocr/
│ ├── cli.py # single image OCR CLI
│ ├── ppt_cli.py # PPT chart OCR CLI
│ ├── ppt_pipeline.py # PPT rendering, layout detection, cropping, and recognition pipeline
│ ├── mcp_server.py # MCP Server entry
│ └── mcp_worker.py # MCP OCR worker subprocess
├── server.py # FastAPI Web service
├── pyproject.toml # project dependencies and command entries
└── uv.lock # uv lock file
```
## FAQ
### 1. First run is slow
First run will download and load PaddleOCR models. Subsequent runs will be significantly faster if models are cached.
### 2. PPT recognition fails
PPT rendering depends on Microsoft PowerPoint COM. Please confirm:
- Current system is Windows
- Microsoft PowerPoint is installed
- PowerPoint can open target PPT normally
- Target file is not a corrupted or password-protected file
### 3. GPU or CUDNN warning
If seeing CUDNN version warnings but recognition is still successful, can continue using. If crashes or abnormal results occur, need to match PaddlePaddle, CUDA, and CUDNN versions.
### 4. MCP tool invocation hangs
Current MCP implementation puts OCR tasks into independent worker subprocesses to avoid Paddle logs and model initialization interfering with stdio MCP protocol. If still hangs, suggest calling `health_check` first, then test PPT process with `detect_only=true`.
### 5. Encoding issue
Windows PowerShell may display Chinese characters as garbled due to non-UTF-8 encoding. JSON files are written in UTF-8, suggest using VS Code or UTF-8-supported editors to view results.
## License
The project has not declared an open-source license yet. Please supplement the License according to actual needs before public release.
