基于 FastMCP 框架和 PaddleOCR-VL 实现的 MCP (Model Context Protocol) OCR 服务器，支持从图片和 PDF 文件中提取结构化文本内容。

• 🚀 基于 FastMCP 2.14+ 框架，代码简洁高效
• 🔤 使用 PaddleOCR-VL 引擎，支持多语言文本识别
• 🌐 HTTP 传输模式，支持远程部署和多客户端访问
• 📊 支持多种输入方式：文件路径、URL、Base64 编码
• 📈 实时进度跟踪
• 📝 结构化 Markdown 输出

• Python 3.8+
• 虚拟环境（推荐）
• 足够的内存（建议 4GB+）

# 创建虚拟环境
python -m venv .venv_paddleocr

# 激活虚拟环境
source .venv_paddleocr/bin/activate  # Linux/Mac
# 或
.venv_paddleocr\Scripts\activate  # Windows

pip install -r requirements_fastmcp_ocr.txt

依赖列表：

• fastmcp>=2.14.2 - MCP 框架
• mcp>=1.0.0 - MCP SDK
• paddleocr>=2.8.0 - OCR 引擎
• httpx>=0.27.0 - HTTP 客户端
• Pillow>=10.0.0 - 图像处理

# 使用启动脚本（推荐）
bash start_fastmcp_ocr.sh

# 或直接运行 Python 脚本
python ocr_mcp_server.py

变量名	默认值	说明
PADDLEOCR_MCP_HOST	0.0.0.0	服务器监听地址
PADDLEOCR_MCP_PORT	8001	服务器端口
PADDLEOCR_MCP_DEVICE	cpu	设备类型（cpu/gpu）
FASTMCP_LOG_LEVEL	WARNING	日志级别

启动后服务器将运行在 http://localhost:8001/mcp

从图片/PDF 中提取结构化内容。

参数：

参数	类型	必需	说明
input_data	string	✓	文件路径、URL 或 Base64 字符串
output_mode	string	✗	输出模式："simple"（仅文本）或 "detailed"（含位置信息）
file_type	string	✗	文件类型："image" 或 "pdf"（URL 方式必需）
return_images	bool	✗	是否返回提取的图像

使用示例：

# 文件路径
await paddleocr_vl(input_data="/path/to/image.png")

# URL
await paddleocr_vl(
    input_data="https://example.com/image.jpg",
    file_type="image"
)

# Base64
await paddleocr_vl(input_data="iVBORw0KGgoAAAANSUhEUg...")

# 详细输出
await paddleocr_vl(
    input_data="/path/to/image.png",
    output_mode="detailed"
)

健康检查端点，返回服务器状态和引擎信息。

await mcp.read_resource("resource://health")

预配置的 OCR 提示模板，用于批量图片识别。

await mcp.get_prompt("ocr_image", image_path="/path/to/image.png")

在 CodeBuddy 配置文件中添加：

{
  "fastmcp-ocr": {
    "type": "http",
    "url": "http://localhost:8001/mcp",
    "args": [],
    "print": true
  }
}

验证连接状态：

codebuddy mcp list

# 启动服务器
bash start_fastmcp_ocr.sh

# 在 CodeBuddy 中使用
codebuddy

然后输入：

请识别 /workspace/example.png 这张图片的内容

import httpx

async def call_ocr(image_path: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8001/mcp",
            json={
                "method": "tools/call",
                "params": {
                    "name": "paddleocr_vl",
                    "arguments": {
                        "input_data": image_path,
                        "output_mode": "simple"
                    }
                }
            }
        )
        return response.json()

# 检查服务器是否运行
ps aux | grep ocr_mcp_server

# 检查端口占用
netstat -tulpn | grep 8001

# 重启服务器
pkill -f ocr_mcp_server
bash start_fastmcp_ocr.sh

# 检查 PaddleOCR 安装
python -c "from paddleocr import PaddleOCRVL; print('OK')"

# 检查图片文件
ls -la /workspace/your_image.png

# 查看日志
# 设置环境变量 FASTMCP_LOG_LEVEL=DEBUG 重新启动

# 使用 CPU 模式
export PADDLEOCR_MCP_DEVICE="cpu"

# 或降低并发数
# 在代码中限制并发请求

/workspace/
├── README.md                      # 项目说明文档
├── ocr_mcp_server.py             # MCP 服务器主文件
├── start_fastmcp_ocr.sh          # 启动脚本
├── requirements_fastmcp_ocr.txt   # Python 依赖
├── FASTMCP_OCR_COMPLETE.md       # 完成报告
└── FASTMCP_OCR_SERVER_GUIDE.md   # 完整使用指南

特性	原版 paddleocr_mcp	FastMCP 版本
框架	FastMCP	FastMCP 2.14+
传输	stdio / HTTP	HTTP (streamable-http)
代码行数	~1000+ 行	~330 行
易于理解	中等	高
进度跟踪	部分	完整
模块化	高	中等

@mcp.tool()
async def custom_ocr_tool(image_data: str, params: dict) -> str:
    """自定义 OCR 工具"""
    engine = get_ocr_engine()
    # 实现自定义逻辑
    return result

# 添加日志中间件
@mcp.middleware
async def log_middleware(request, call_next):
    print(f"Processing: {request.method}")
    response = await call_next(request)
    return response

def convert_to_custom_format(ocr_result: list) -> str:
    """自定义输出格式"""
    # 实现自定义格式转换
    return formatted_text

• 添加 GPU 支持
• 实现批量处理
• 添加缓存机制
• 支持更多图像格式
• 添加 Docker 部署支持

欢迎提交 Issue 和 Pull Request！

MIT License

• FastMCP 文档
• PaddleOCR 文档
• MCP 协议
• FastMCP 技能文档

如有问题或建议，请提交 Issue。

---

最后更新: 2026-01-22 FastMCP 版本: 2.14+ PaddleOCR 版本: 2.8+