as8457632

OCR MCP

Community as8457632
Updated

OCR MCP:多模态 OCR 识别(服务端 + 客户端)

OCR MCP

基于多模态模型的 OCR 识别 MCP 工具,分服务端客户端两部分:

  • 服务端 ocr-mcp-server:持有模型密钥(base_url / api_key / model),以 Streamable HTTP 对外提供 ocr_image 工具,真正调用多模态模型做文字识别。
  • 客户端 ocr-mcp-client:以 stdio 方式挂载到任意 IDE(Cursor / Claude Code / Codex / Claude Desktop 等),提供 ocr_image 工具,把本地图片转成 base64 后,通过配置的服务端地址调用远端 OCR 服务。
┌──────────────┐   stdio    ┌───────────────────┐  Streamable HTTP  ┌────────────────────┐
│ IDE (任意)   │ ─────────▶ │ ocr-mcp-client     │ ────────────────▶ │ ocr-mcp-server     │
│ Cursor/CC/.. │            │ 图片 → base64 转发  │                   │ 多模态模型 OCR 识别  │
└──────────────┘            └───────────────────┘                   └────────────────────┘

目录结构

ocr-mcp/
├── pyproject.toml                    # uv workspace 根
└── packages/
    ├── ocr-mcp-server/               # 服务端:Streamable HTTP MCP
    │   └── src/ocr_mcp_server/
    │       ├── config.py             # 环境变量配置
    │       ├── ocr.py                # 调用多模态模型识别文字
    │       ├── server.py             # MCP Server + ocr_image 工具
    │       └── app.py                # /mcp 的 ASGI 应用
    └── ocr-mcp-client/               # 客户端:stdio MCP
        ├── skill/                    # 配套 Agent Skill(ocr-mcp)
        │   └── SKILL.md
        └── src/ocr_mcp_client/
            ├── config.py             # 环境变量配置
            ├── remote.py             # 通过 Streamable HTTP 调用服务端
            └── server.py             # MCP Server + ocr_image 工具

快速开始

需要 uv(≥ 0.4)和 Python ≥ 3.11。

uv sync --all-packages --group dev

1. 启动服务端(部署在内网,持有模型密钥)

默认配置:两端都支持从项目根目录(或任意上级目录)的 .env 文件读取配置,无需每次手动 export。例如在仓库根目录创建 .env

OCR_MCP_BASE_URL="https://your-model-endpoint/v1"
OCR_MCP_API_KEY="sk-..."
OCR_MCP_MODEL="qwen-vl-max"
OCR_MCP_PORT="18000"

.env 已被 .gitignore 忽略,密钥不会提交。已存在的环境变量优先于 .env

export OCR_MCP_BASE_URL="https://your-model-endpoint/v1"
export OCR_MCP_API_KEY="sk-..."
export OCR_MCP_MODEL="qwen-vl-max"        # 你的多模态模型名
# 可选
export OCR_MCP_HOST="0.0.0.0"             # 默认 0.0.0.0
export OCR_MCP_PORT="8000"                # 默认 8000
export OCR_MCP_TIMEOUT="60"               # 模型调用超时(秒),默认 60

uv run ocr-mcp-server

服务端启动后监听 http://<host>:8000/mcp。客户端通过 OCR_MCP_SERVER_URL 指向该地址。

2. 配置客户端

客户端是一个 stdio MCP server,需要设置 OCR_MCP_SERVER_URL 指向服务端地址(可选 OCR_MCP_SERVER_TOKEN,用于带 Bearer Token 访问服务端):

export OCR_MCP_SERVER_URL="http://<server-host>:8000/mcp"
# export OCR_MCP_SERVER_TOKEN="..."       # 可选,若服务端要求鉴权
无源码机器:从 GitHub 安装客户端

其他机器不需要克隆整个仓库,用 uv tool 只装客户端即可。仓库为私有,安装前需能访问 GitHub(SSH key,或 gh auth login / GIT_ASKPASS / HTTPS token)。

# 需已安装 uv(https://docs.astral.sh/uv/)
# HTTPS(需已配置有 repo 读权限的凭据)
uv tool install "git+https://github.com/as8457632/ocr-mcp.git#subdirectory=packages/ocr-mcp-client"

# 或 SSH
uv tool install "git+ssh://[email protected]/as8457632/ocr-mcp.git#subdirectory=packages/ocr-mcp-client"

# 确认命令可用
which ocr-mcp-client
# 常见路径:~/.local/bin/ocr-mcp-client

IDE MCP 配置请使用绝对路径(很多 IDE 的 PATH 找不到 ~/.local/bin):

{
  "mcpServers": {
    "ocr-mcp": {
      "command": "/home/<用户>/.local/bin/ocr-mcp-client",
      "args": [],
      "env": {
        "OCR_MCP_SERVER_URL": "http://<OCR服务端IP>:18000/mcp"
      }
    }
  }
}

升级客户端:

uv tool upgrade ocr-mcp-client
# 或重新安装同一 git URL
uv tool install --force "git+https://github.com/as8457632/ocr-mcp.git#subdirectory=packages/ocr-mcp-client"

3. IDE 配置示例(本机有仓库时)

本机已 uv sync 过仓库时,可用 uv run 拉起客户端,环境变量由各 IDE 注入。下面给四种常见配置。

Cursor(项目根 .mcp.json):

{
  "mcpServers": {
    "ocr-mcp": {
      "command": "uv",
      "args": ["run", "ocr-mcp-client"],
      "env": {
        "OCR_MCP_SERVER_URL": "http://<server-host>:8000/mcp"
      }
    }
  }
}

Claude Code

claude mcp add ocr-mcp -- uv run ocr-mcp-client \
  -e OCR_MCP_SERVER_URL=http://<server-host>:8000/mcp

或写入 ~/.claude.jsonmcpServers 段(同上 JSON 结构)。

Codex CLI~/.codex/config.toml):

[mcp_servers.ocr-mcp]
command = "uv"
args = ["run", "ocr-mcp-client"]
env = { OCR_MCP_SERVER_URL = "http://<server-host>:8000/mcp" }

也可用 codex mcp add ocr-mcp -- uv run ocr-mcp-client 后追加环境变量。

Claude Desktopclaude_desktop_config.json):

{
  "mcpServers": {
    "ocr-mcp": {
      "command": "uv",
      "args": ["run", "ocr-mcp-client"],
      "env": {
        "OCR_MCP_SERVER_URL": "http://<server-host>:8000/mcp"
      }
    }
  }
}

4. 安装配套 Agent Skill(可选)

客户端附带 Agent 操作手册,教 Agent 何时调用 ocr_image、如何传参与排障。源文件:

packages/ocr-mcp-client/skill/SKILL.md

拷贝到各 IDE 的 skills 目录即可(目录名保持 ocr-mcp):

# Cursor(个人技能)
mkdir -p ~/.cursor/skills/ocr-mcp
cp packages/ocr-mcp-client/skill/SKILL.md ~/.cursor/skills/ocr-mcp/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/ocr-mcp
cp packages/ocr-mcp-client/skill/SKILL.md ~/.claude/skills/ocr-mcp/SKILL.md

也可放到项目内 .cursor/skills/ocr-mcp/,仅对当前仓库生效。Skill 假定 MCP 已配置;安装 MCP 见上文。

工具

两端都暴露一个工具 ocr_image

参数 类型 必填 说明
image string 客户端:本地图片路径或 http(s):// 图片 URL;服务端:data URI 或 http(s):// URL
prompt string 自定义识别提示词,默认按 OCR 场景优化
mode string 识别模式:plain(默认,保持排版输出纯文本)或 structured(输出 Markdown 结构化文本:标题/列表/表格)

mode=structured 示例输出(界面截图):

# 遇·见
- 首页
- 代码仓库
- 工作空间

## 控制台

| 本周增长 | 0% |
| ------- | -- |

### 快捷入口
- AI 知识问答
- 知识库

返回结构(客户端):

{
  "text": "识别出的全部文字",
  "source": "用户传入的图片路径或 URL"
}

环境变量一览

变量 用途 必填 默认
OCR_MCP_BASE_URL 多模态模型 API 地址(OpenAI 兼容) 服务端必填
OCR_MCP_API_KEY 模型 API 密钥 服务端必填
OCR_MCP_MODEL 模型名称 服务端必填
OCR_MCP_HOST / OCR_MCP_PORT 服务端监听地址 0.0.0.0 / 8000
OCR_MCP_TIMEOUT 模型调用 / 远端调用超时(秒) 60
OCR_MCP_SERVER_URL 服务端 MCP 地址(客户端) 客户端必填
OCR_MCP_SERVER_TOKEN 访问服务端的 Bearer Token(客户端)

开发

uv run pytest          # 全部测试(含服务端/客户端 e2e)
uv run --with mypy mypy packages/*/src
uv run --with ruff ruff check packages

MCP Server · Populars

MCP Server · New

    qcri

    🦡 codebadger

    🦡 codebadger is a containerized Model Context Protocol (MCP) server that gives AI agents and LLMs deep, queryable access to a codebase's structure and data flow through Joern Code Property Graphs (CPGs).

    Community qcri
    boringSQL

    DryRun PostgreSQL MCP

    PostgreSQL schema intelligence MCP server with offline linting, migration safety, query validation for AI coding assistants.

    Community boringSQL
    emerzon

    mtdata

    A MetaTrader 5 research toolkit with 90+ AI tools for forecasting, regime detection, pattern recognition, and live trading.

    Community emerzon
    OpenImageDebugger

    Open Image Debugger: Enabling visualization of in-memory buffers on GDB/LLDB

    An advanced in-memory image visualization plugin for GDB and LLDB on Linux, with experimental support for MacOS and Windows. Previously known as gdb-imagewatch. Also available as an extension for VSCode and forks

    Community OpenImageDebugger
    HQBase

    HQBase

    Your team's email workspace. In your Cloudflare account.

    Community HQBase