MCP-OCR

为 Claude Code、Codex CLI、OpenCode 等 AI 编程工具补齐图像识别能力的 MCP Server。

解决什么问题

Claude Code 配合 DeepSeek 等纯文本模型使用时，无法理解图片内容——截图里的报错、UI 设计稿、手绘架构图、文档扫描件，模型统统"看不见"。

mcp-vision 作为 MCP Server 插件运行，自动调用多模态视觉 API 完成图像分析，将结果以文本形式返回给 AI 编程工具，让 DeepSeek 等"看图说话"。

┌─────────────┐     图片路径/URL      ┌─────────────┐    多模态 API     ┌──────────────┐
│  AI 编程工具  │ ──────────────────→  │ mcp-vision  │ ──────────────→  │  视觉模型 API  │
│ Claude Code  │                      │  MCP Server  │                  │ 硅基流动/阿里.. │
│  Codex CLI   │ ←──────────────────  │             │ ←──────────────  │              │
│   OpenCode   │     文字分析结果      │             │     图片分析结果   │              │
└─────────────┘                      └─────────────┘                  └──────────────┘

工具说明

| 工具 | 用途 | 底层 | |------|------|------| | analyze_image | 图片内容分析（描述、问答、图表解读） | 多模态 LLM | | ocr_extract | 从图片/PDF 提取文字（自然语言返回） | 多模态 LLM | | ocr_precise | 精准 OCR（结构化结果，含坐标和置信度） | 传统 OCR 引擎 |

所有工具均支持本地文件路径和远程 URL。

快速开始

安装

pip install mcp-vision

或使用 uv：

uv pip install mcp-vision

最简配置

只需一个 API Key 即可运行。推荐使用硅基流动（SiliconFlow），注册即送免费额度：

# 注册地址：https://cloud.siliconflow.cn
SILICONFLOW_API_KEY=sk-your-key

配置 AI 编程工具

Claude Code

~/.claude/settings.json：

{
  "mcpServers": {
    "mcp-vision": {
      "command": "uvx",
      "args": ["mcp-vision"],
      "env": {
        "SILICONFLOW_API_KEY": "sk-your-key"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml：

[mcp_servers.mcp-vision]
command = "uvx"
args = ["mcp-ocr"]

[mcp_servers.mcp-vision.env]
SILICONFLOW_API_KEY = "sk-your-key"

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "mcp-vision": {
      "command": "uvx",
      "args": ["mcp-vision"],
      "env": {
        "SILICONFLOW_API_KEY": "sk-your-key"
      }
    }
  }
}

OpenCode

opencode.json：

{
  "mcp": {
    "mcp-vision": {
      "type": "local",
      "command": ["uvx", "mcp-vision"],
      "environment": {
        "SILICONFLOW_API_KEY": "sk-your-key"
      }
    }
  }
}

支持的 Provider

通过 MCP_OCR_PROVIDER 环境变量切换，默认 siliconflow。

多模态 LLM（图片分析 / OCR 提取）

| Provider | 值 | API Key 环境变量 | 默认模型 | |----------|---|-----------------|---------| | 硅基流动（默认） | siliconflow | SILICONFLOW_API_KEY | DeepSeek-OCR | | 阿里百炼 | dashscope | DASHSCOPE_API_KEY | qwen-vl-max | | 火山引擎 | volcengine | VOLCENGINE_API_KEY | doubao-1.5-vision-pro-32k | | OpenAI | openai | OPENAI_API_KEY | gpt-4o | | Anthropic | anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 | | 自定义 API | custom | MCP_OCR_API_KEY | 需手动指定 |

硅基流动以外的 Provider 需额外设置对应的模型环境变量（如 DASHSCOPE_MODEL、OPENAI_MODEL）。

切换视觉模型

每个 Provider 都有内置默认模型，通过对应的 *_MODEL 环境变量可以覆盖：

| Provider | 模型环境变量 | 默认值 | |----------|------------|-------| | 硅基流动 | SILICONFLOW_MODEL | deepseek-ai/DeepSeek-OCR | | 阿里百炼 | DASHSCOPE_MODEL | qwen-vl-max | | 火山引擎 | VOLCENGINE_MODEL | doubao-1.5-vision-pro-32k | | OpenAI | OPENAI_MODEL | gpt-4o | | Anthropic | ANTHROPIC_MODEL | claude-sonnet-4-6 |

以硅基流动为例，在 .env 或环境变量中指定：

MCP_OCR_PROVIDER=siliconflow
SILICONFLOW_API_KEY=sk-your-key
SILICONFLOW_MODEL=deepseek-ai/DeepSeek-OCR

在 AI 编程工具的 env 配置中直接指定：

{
  "mcpServers": {
    "mcp-vision": {
      "command": "uvx",
      "args": ["mcp-vision"],
      "env": {
        "SILICONFLOW_API_KEY": "sk-your-key",
        "SILICONFLOW_MODEL": "Qwen/Qwen2.5-VL-72B-Instruct"
      }
    }
  }
}

提示：请确保指定的模型是视觉模型（支持图片输入）。纯文本模型会导致 API 调用失败。

传统 OCR（精准提取，结构化结果）

| Provider | 值 | 环境变量 | |----------|---|---------| | 百度 OCR | baidu_ocr | BAIDU_OCR_API_KEY + BAIDU_OCR_SECRET_KEY | | 腾讯云 OCR | tencent_ocr | TENCENT_SECRET_ID + TENCENT_SECRET_KEY |

传统 OCR 仅支持 ocr_precise 工具，返回结构化数据（含文字坐标和置信度）。

自定义 Provider

兼容所有 OpenAI /chat/completions 协议的视觉 API：

MCP_OCR_PROVIDER=custom
MCP_OCR_API_KEY=your-key
MCP_OCR_BASE_URL=https://your-api.com/v1
MCP_OCR_MODEL=your-vision-model

环境变量完整列表

# Provider 选择（默认 siliconflow）
MCP_OCR_PROVIDER=siliconflow

# === 硅基流动 ===
SILICONFLOW_API_KEY=your-key
# SILICONFLOW_MODEL=deepseek-ai/DeepSeek-OCR    # 可选，覆盖默认模型

# === 阿里百炼 ===
# DASHSCOPE_API_KEY=your-key
# DASHSCOPE_MODEL=qwen-vl-max

# === 火山引擎 ===
# VOLCENGINE_API_KEY=your-key
# VOLCENGINE_MODEL=doubao-1.5-vision-pro-32k

# === OpenAI ===
# OPENAI_API_KEY=sk-your-key
# OPENAI_MODEL=gpt-4o

# === Anthropic ===
# ANTHROPIC_API_KEY=sk-ant-your-key
# ANTHROPIC_MODEL=claude-sonnet-4-6

# === 百度 OCR ===
# BAIDU_OCR_API_KEY=your-api-key
# BAIDU_OCR_SECRET_KEY=your-secret-key

# === 腾讯云 OCR ===
# TENCENT_SECRET_ID=your-secret-id
# TENCENT_SECRET_KEY=your-secret-key

# === 自定义 OpenAI 兼容 API ===
# MCP_OCR_API_KEY=your-key
# MCP_OCR_BASE_URL=https://your-api.com/v1
# MCP_OCR_MODEL=your-model

也可将这些变量写在项目根目录的 .env 文件中，Server 启动时自动加载。

图片格式

PNG、JPG、JPEG、GIF、BMP、WebP、PDF

自动触发：粘贴图片即分析

在 Claude Code 中可以通过 Skill 实现粘贴图片后自动调用 mcp-vision，无需手动输入命令。

步骤一：创建 Skill 文件

在项目根目录创建 .claude/skills/image-analysis.md：

---
name: image-analysis
description: 当用户粘贴图片时自动调用 mcp-vision 进行分析
trigger: 当用户消息中包含图片（[Image: ...] 或 [Image #N] 标记）时自动触发
---

当用户消息中包含图片标记时，自动调用 mcp-vision 的工具处理：

1. **如果用户没有文字说明**，默认调用 `analyze_image` 工具分析图片内容
2. **如果用户附带了文字说明**，将文字说明作为 prompt 传给对应工具

根据用户意图选择工具：
- 图片描述、问答、图表分析 → `analyze_image`
- 提取文字 → `ocr_extract`
- 需要坐标和置信度 → `ocr_precise`

图片路径直接从图片标记中提取，作为 image 参数传入。

步骤二：在 CLAUDE.md 中注册触发规则

在项目的 CLAUDE.md（或全局 ~/.claude/CLAUDE.md）中添加：

### 图片自动分析
- **触发条件**：当用户消息中包含 `[Image:`、`[Image #N]` 标记时（即通过 Alt+V 粘贴的图片）
- **执行动作**：立即调用 `image-analysis` skill，根据图片内容和用户意图自动选择分析模式
- **无需用户明确指示**：只要消息中有图片就应触发，无文字说明时自动智能路由

效果

配置完成后：

Alt+V 粘贴图片 → Claude Code 自动调用 mcp-vision 的 analyze_image → 返回图片分析结果
粘贴图片 + 文字说明（如"提取这里的文字"） → 自动路由到 ocr_extract
无需手动输入任何命令

本地开发

# 克隆仓库
git clone https://github.com/hahahahanb/mcp-vision.git
cd mcp-vision

# 安装依赖
uv sync

# 运行测试
uv run pytest -v

# MCP Inspector 调试
uv run mcp dev src/mcp_ocr/server.py

本地安装后，AI 编程工具的配置可改为直接运行源码：

{
  "mcpServers": {
    "mcp-vision": {
      "command": "uv",
      "args": ["run", "mcp-vision"],
      "env": {
        "SILICONFLOW_API_KEY": "sk-your-key"
      }
    }
  }
}

License

MIT

MCP Servers