mcp-vision
Summary: mcp-vision is an MCP server that gives text-only AI coding tools (Claude Code, Codex CLI, OpenCode, Cursor) image understanding by forwarding images to multimodal vision APIs and returning text results.
analyze_image— describe images, answer visual questions, and interpret charts/diagrams; accepts a local absolute path or remote URL plus an optional analysis prompt.ocr_extract— pull and format text out of images or PDFs (screenshots, documents, code) using a multimodal LLM; optional OCR prompt.ocr_precise— precise OCR with structured output including text coordinates and confidence, backed by traditional engines (Baidu OCR or Tencent Cloud OCR, which must be configured).Pluggable providers — switch via
MCP_OCR_PROVIDER: SiliconFlow (default), DashScope/Aliyun Bailian, Volcengine, OpenAI, Anthropic, or any OpenAI-compatible custom endpoint.Broad input support — PNG, JPG, JPEG, GIF, BMP, WebP, and PDF; keys supplied via env vars or a
.envfile.Drop-in setup — install with
pip/uvand run viauvx/uvin the MCP config of supported coding tools; a Claude Code skill can auto-trigger analysis on pasted images.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-vision describe this image: ./screenshot.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP-VISION
为 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 │ 文字分析结果 │ │ 图片分析结果 │ │
└─────────────┘ └─────────────┘ └──────────────┘Related MCP server: vision-mcp
工具说明
工具 | 用途 | 底层 |
| 图片内容分析(描述、问答、图表解读) | 多模态 LLM |
| 从图片/PDF 提取文字(自然语言返回) | 多模态 LLM |
| 精准 OCR(结构化结果,含坐标和置信度) | 传统 OCR 引擎 |
所有工具的 image 参数均支持单个本地文件路径或远程 URL,也支持按顺序传入多个路径/URL 的列表。多模态 Provider 会在一次请求中联合处理多张图片;精准 OCR 会逐张调用传统 OCR 服务并按图片分段返回。
配置百度或腾讯传统 OCR Provider 时,多图输入请使用 ocr_precise。图片的数量、格式和总请求体大小仍需满足所选服务和模型的限制。
快速开始
安装
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 环境变量 | 默认模型 |
硅基流动(默认) |
|
| DeepSeek-OCR |
阿里百炼 |
|
| qwen-vl-max |
火山引擎 |
|
| doubao-1.5-vision-pro-32k |
OpenAI |
|
| gpt-4o |
Anthropic |
|
| claude-sonnet-4-6 |
自定义 API |
|
| 需手动指定 |
硅基流动以外的 Provider 需额外设置对应的模型环境变量(如 DASHSCOPE_MODEL、OPENAI_MODEL)。
切换视觉模型
每个 Provider 都有内置默认模型,通过对应的 *_MODEL 环境变量可以覆盖:
Provider | 模型环境变量 | 默认值 |
硅基流动 |
|
|
阿里百炼 |
|
|
火山引擎 |
|
|
OpenAI |
|
|
Anthropic |
|
|
以硅基流动为例,在 .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 |
|
|
腾讯云 OCR |
|
|
传统 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
Available Tools
3 toolsanalyze_imageA
分析图片内容。支持本地文件路径和远程 URL。可用于图像描述、视觉问答、图表分析等场景。
Args: image: 图片路径(本地绝对路径)或远程 URL prompt: 分析提示词,描述你希望如何分析这张图片。默认详细描述图片内容
Inputs: image (required), prompt. Returns: result
ocr_extractA
从图片或 PDF 中提取文字(OCR)。适合识别截图、文档、代码中的文本内容。
Args: image: 图片或 PDF 文件路径(本地绝对路径)或远程 URL prompt: OCR 提示词。默认提取并格式化所有文字内容
Inputs: image (required), prompt. Returns: result
ocr_preciseA
使用传统 OCR 引擎精准提取图片中的文字(返回结构化结果,含文字坐标和置信度)。 需要配置百度 OCR 或腾讯云 OCR 作为 Provider。 适合需要精确文字位置信息的场景(如发票、卡证、表格)。
Args: image: 图片文件路径(本地绝对路径)或远程 URL
Inputs: image (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Most tools are distinct: analyze_image handles general analysis, while ocr_extract and ocr_precise both do OCR but differ in precision and output structure. However, an agent might confuse ocr_extract with ocr_precise since both extract text.
Two tools follow an 'ocr_' prefix pattern, while analyze_image uses a different verb_noun structure. The naming is mostly consistent within subgroups but lacks a unified pattern across all tools.
3 tools is slightly thin for a 'vision' server, but covers core analysis and OCR functions. The count is appropriate for a focused utility, though more tools could be beneficial.
Basic image analysis and OCR are covered, but missing common vision tasks like object detection or image manipulation. The toolset feels minimal for general vision needs, leaving notable gaps.
Maintenance
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for Qwen Image 3 AI image generation
An MCP server that integrates with Discord to provide AI-powered features.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server that analyzes images, reads code and ZIP archives, and provides text context for non-vision models.37 npm2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for image recognition and OCR via OpenAI-compatible vision APIs, supporting local files, URLs, and data URLs. Enables natural language image description and text extraction.2MIT
- FlicenseNot gradedqualityBmaintenanceA lightweight MCP server that provides vision capabilities to text-only models like Claude Code and Codex by forwarding images to an OpenAI-compatible multimodal model, offering tools for image analysis and OCR.-
- AlicenseAqualityDmaintenanceMCP server that provides visual question answering, image description, object detection, OCR, and image manipulation tools using OpenAI-compatible vision models.12488 npmGPL 2.0