deepseek-vision-mcp

为没有视觉能力的大模型（如 DeepSeek 等纯文本模型）补齐图片识别 / OCR 能力的通用 MCP 服务器。基于 OpenAI 兼容协议，一套代码可对接任意支持该协议的多模态厂家（智谱、OpenAI、通义千问、Kimi 等）。

解决什么问题：DeepSeek 等模型"看不见"图片。通过本 MCP 服务器，Claude Code 等 MCP 客户端可以调用任一家视觉模型分析图片、提取文字，再把结果以文本形式交给模型——让 DeepSeek 也能"看图"。

---

⚠️ 安全警告（必读）

• API Key 只能放在 .env 文件中，.env 已被 .gitignore 排除，永远不会被提交到 git / GitHub。
• 绝对不要把 .env、或任何包含 Key 的内容复制、提交或公开。
• 本项目开源的是代码，密钥由你自己在本地配置。
• 若 Key 意外泄露，请立即到对应厂家平台删除并重新生成，避免产生费用损失。

---

功能特性

工具	说明
analyze_image(image, prompt)	分析 / 描述图片，支持本地路径、URL、base64
ocr_image(image)	提取图片中的全部文字（OCR）
list_models()	查看当前配置与常用视觉模型端点

• 多厂家通用：任意 OpenAI 兼容多模态端点，改 3 个环境变量即切换
• 默认使用智谱免费模型 glm-4.6v-flash（128K 上下文，零成本）
• 支持 jpg / jpeg / png / webp / gif / bmp，单张 < 10MB
• 内置 429 限流指数退避自动重试
• 基于 FastMCP，单文件即可运行

支持厂家（改配置即切换）

厂家	VISION_BASE_URL	示例模型
智谱 AI	https://open.bigmodel.cn/api/paas/v4	glm-4.6v-flash（免费）/ glm-4.6v
OpenAI	https://api.openai.com/v1	gpt-4o / gpt-4o-mini
阿里云通义千问	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-vl-max / qwen-vl-plus
Kimi (Moonshot)	https://api.moonshot.cn/v1	moonshot-v1-vision-preview / kimi-latest

其他支持 OpenAI 兼容接口的多模态厂家均可，按同样方式配置即可。

环境要求

• Python 3.10 及以上
• pip（Python 包管理器）

安装

# 1. 获取本项目
git clone https://github.com/<你的GitHub用户名>/deepseek-vision-mcp.git
cd deepseek-vision-mcp

# 2. 安装依赖
pip install fastmcp python-dotenv

配置 API Key

1. 注册任一家支持视觉模型的平台并获取 Key（如智谱：https://open.bigmodel.cn/ → API Keys → 创建）
2. 复制 .env.example 为 .env：

cp .env.example .env

3. 编辑 .env，填入你的 Key 并选择厂家：

# 例：智谱（免费）
VISION_API_KEY=你的智谱APIKey
VISION_BASE_URL=https://open.bigmodel.cn/api/paas/v4
VISION_MODEL=glm-4.6v-flash

# 例：OpenAI（改三行即切换）
# VISION_API_KEY=sk-你的OpenAIKey
# VISION_BASE_URL=https://api.openai.com/v1
# VISION_MODEL=gpt-4o-mini

完整的多厂家示例见 .env.example。

注册到 Claude Code

claude mcp add zhipu-vision -- python D:/你的路径/server.py

提示：Windows 下路径含反斜杠可能被 shell 转义，建议使用正斜杠路径：

claude mcp add zhipu-vision -- python D:/claude/zhipu-vision-mcp/server.py

默认注册在当前项目作用域；如需所有项目可用，追加参数 -s user。

验证注册：

claude mcp list

看到 zhipu-vision: ... ✔ Connected 即注册成功。

使用

注册并重启 Claude Code 会话后，直接对话即可（系统会自动调用 MCP 工具）：

识别这张图：D:\图片\photo.png
看下这张图里有什么
提取这个截图里的文字

也可以显式指定工具：

• 要求分析：用 analyze_image 分析 D:\图片\photo.png
• 要求 OCR：用 ocr_image 提取 D:\截图\code.png 的文字

支持的图片来源

类型	示例
本地路径	D:\图片\photo.png
远程 URL	https://example.com/image.png
base64 数据	data:image/png;base64,xxxxx

独立测试（不通过 MCP）

python make_test_image.py   # 生成带文字 "TEST 123" 的测试图
python test_server.py       # 调用 analyze_image / ocr_image 验证 API 链路

常见问题

• 401 错误：API Key 无效或未在 .env 配置，检查后重试。
• 429 错误：厂家限流，服务器已自动指数退避重试；频繁使用建议换付费模型或提高配额。
• 图片过大：单张需 < 10MB，超限请先压缩。
• 找不到 MCP 工具：确认已执行 claude mcp add ... 并重启会话。
• 如何切换厂家：修改 .env 中的 VISION_BASE_URL 和 VISION_MODEL，重启 MCP 服务器。

License

MIT

免责声明

本项目仅提供视觉模型调用封装，与 DeepSeek、智谱 AI 等均无官方关联。使用各厂家 API 需遵守其服务条款；请自行妥善保管 API Key。