deepseek-vision-mcp

让纯文本大语言模型 Agent（如 DeepSeek 系）获得「眼睛」的 MCP 项目：通过标准 MCP 工具调用智谱 GLM-4.6V-Flash（免费视觉模型），完成图片 / 视频 / 文件三种模态的理解，并以纯文本结果回传给 Agent。

底层模型：智谱 GLM-4.6V-Flash（免费，128K 上下文，支持思考模式） 官方文档：https://docs.bigmodel.cn/cn/guide/models/free/glm-4.6v-flash

架构：MCP 执行层 + Skill 决策层

┌─────────────────────────────────────────────────────┐
│  文本模型 Agent（DeepSeek 等）—— 只懂文字            │
│  · 读取 Skill 的业务规则，决定何时调用什么工具        │
└──────────────────────┬──────────────────────────────┘
                       │ MCP 协议（stdio）
┌──────────────────────▼──────────────────────────────┐
│  MCP Server（本仓库，Python）—— 真实执行             │
│  · 读本地文件 / 图片 → base64 编码                    │
│  · 调用智谱 API（认证、重试、超时、异常分类）          │
│  · 提供标准化工具：vision_analyze_image / _video / _file │
└──────────────────────┬──────────────────────────────┘
                       │ HTTPS
┌──────────────────────▼──────────────────────────────┐
│  智谱 GLM-4.6V-Flash API（视觉理解，返回文本）        │
└─────────────────────────────────────────────────────┘

职责分离：

层	职责	位置
MCP	真实执行：读文件、base64、调 API、重试、异常捕获、统一错误结构	deepseek_vision_mcp/
Skill	业务规则：何时调用、传什么参数、输出格式、降级策略	skills/vision-agent/SKILL.md

功能

• 图片理解：本地图片路径（自动 base64）或公网 URL
• 视频理解：公网视频 URL（本地视频需先提供可访问 URL）
• 文件理解：PDF / 文本等文档（公网 URL；本地文件需先提供可访问 URL）
• 思考模式：可选开启（thinking=true），适合需要深度推理的视觉任务
• 健壮性：3 次指数退避重试（429 / 5xx / 超时）、60s 超时、结构化错误返回（不抛未处理异常）

安装与部署

1. 前置条件

项目	要求
Python	≥ 3.10（Windows / macOS / Linux 均可）
智谱 API Key	免费申请：登录 智谱开放平台 后进入个人中心 → API Keys（https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys）创建（GLM-4.6V-Flash 是免费模型，无需充值）

检查 Python 版本：

python --version    # 或 python3 --version

若未安装 Python：Windows 用 winget install Python.Python.3.12 --scope user，macOS 用 brew install python@3.12，Linux 用 apt install python3 等。

2. 安装软件包（四种方式任选其一）

方式 A：一条命令直接安装（推荐）

pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.1.0-py3-none-any.whl"

国内网络下载依赖较慢时加镜像源（wheel 本体仍从 GitHub 拉取，只有依赖走镜像）：

pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.1.0-py3-none-any.whl" -i https://pypi.tuna.tsinghua.edu.cn/simple

方式 B：手动下载 wheel 后安装

1. 打开 Release 页面：https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/tag/v0.1.0
2. 在 Assets 区下载 deepseek_vision_mcp-0.1.0-py3-none-any.whl
3. 本地安装：pip install deepseek_vision_mcp-0.1.0-py3-none-any.whl

方式 C：源码包（sdist，含 skills/ 决策层文件与测试）

下载 deepseek_vision_mcp-0.1.0.tar.gz 后：pip install deepseek_vision_mcp-0.1.0.tar.gz

方式 D：克隆仓库开发安装

git clone https://github.com/JunHua-ECJTU/deepseek-vision-mcp.git
cd deepseek-vision-mcp && pip install -e ".[dev]"

不想污染全局环境时，先建虚拟环境再安装：

python -m venv .venv
# Windows：.venv\Scripts\activate    macOS/Linux：source .venv/bin/activate
pip install ...（上面任一方式）

验证安装成功：

python -c "from deepseek_vision_mcp.server import main; print('deepseek-vision-mcp OK')"

3. 配置 API Key（三选一）

方式 1：环境变量（临时，当前终端有效）

# Windows PowerShell
$env:ZHIPU_API_KEY = "你的Key"
# macOS / Linux
export ZHIPU_API_KEY="你的Key"

方式 2：.env 文件（推荐；MCP server 启动时自动读取当前工作目录的 .env）

echo "ZHIPU_API_KEY=你的Key" > .env

方式 3：MCP 配置文件的 env 字段（见第 4 节各 Agent 模板）

4. 注册到你的 Agent（MCP 客户端）

通用 .mcp.json（Claude Code / Cursor / Cline / Continue / Windsurf 等）——项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "python",
      "args": ["-m", "deepseek_vision_mcp.server"],
      "env": { "ZHIPU_API_KEY": "你的Key" }
    }
  }
}

Claude Desktop——菜单 → Settings → Developer → Edit Config，写入同样的 JSON 后重启。

Reasonix——编辑 %APPDATA%\reasonix\config.toml（Windows）或 ~/.reasonix/config.toml：

[[plugins]]
name = "deepseek-vision"
command = "python"
args = ["-m", "deepseek_vision_mcp.server"]
env = { ZHIPU_API_KEY = "${ZHIPU_API_KEY}" }
startup_timeout_seconds = 60
call_timeout_seconds = 120

并把 Key 放入与 config.toml 同目录的 .env（${VAR} 由 Reasonix 从环境展开，密钥不入配置文件）；重启或点「刷新插件」。

其他 MCP 客户端——任何支持 stdio MCP 的客户端都等价于：

字段	值
command	python
args	["-m", "deepseek_vision_mcp.server"]
env	ZHIPU_API_KEY=<你的Key>

Windows 下 python 不在 PATH 时，把 command 换成完整路径，如 C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe。

5.（可选）安装 Skill 业务规则层

Skill 指导 Agent「何时调用工具、传什么参数、输出什么格式、失败怎么降级」。从源码包（方式 C）或仓库中取出 skills/vision-agent/ 目录，复制到你的 Agent 的 skills 目录（各 Agent 约定不同，通常是 ~/.agent/skills/ 或项目 .agent/skills/），重启会话生效。

6. 验证是否可用

方法 1：MCP Inspector 官方工具

npx @modelcontextprotocol/inspector python -m deepseek_vision_mcp.server

应看到 3 个工具：vision_analyze_image / vision_analyze_video / vision_analyze_file。

方法 2：直接问你的 Agent

分析这张图片：https://cdn.bigmodel.cn/static/logo/register.png

或本地图片：

帮我看一下 C:\photo\receipt.jpg 里的金额是多少

7. 常见问题

现象	处理
工具返回 AUTH_ERROR	Key 未配置或无效，检查第 3 节
工具返回 MODALITY_NOT_SUPPORTED	视频/文件传了本地路径——视频/文件模态只接受公网 URL，先上传到可访问地址
工具返回 API_ERROR（HTTP 429）	智谱免费模型限流（"访问量过大"），稍后重试或避开高峰
启动报 ModuleNotFoundError: mcp	依赖未装全，补装：pip install mcp httpx python-dotenv
Agent 找不到工具	MCP 注册配置有误；检查 JSON 语法与 command 是否可执行

更多细节（各 Agent 配置、MCP Inspector 用法、故障排查表）见 docs/DEPLOY.md。

MCP 工具

工具	说明	关键参数
vision_analyze_image	图片理解（本地路径或 URL）	source、question、thinking
vision_analyze_video	视频理解（URL）	source、question、thinking
vision_analyze_file	文件理解（URL，PDF/文本等）	source、question、thinking

所有工具返回统一结构：

{
  "ok": true,
  "content": "模型的文本回答",
  "thinking": "思考内容（如开启）",
  "usage": { "prompt_tokens": 123, "completion_tokens": 45 }
}

失败时返回 {"ok": false, "error": {"code": "...", "message": "..."}}，错误码包括 FILE_NOT_FOUND、UNSUPPORTED_FORMAT、AUTH_ERROR、API_ERROR、TIMEOUT、MODALITY_NOT_SUPPORTED 等。

注意事项

• GLM-4.6V-Flash 不支持同时理解多种模态（图片/视频/文件一次只传一种）——Skill 层已约束
• 视频/文件模态要求可访问的 URL（本地路径需先上传到可访问位置）
• .env 已加入 .gitignore，API Key 永不入库

测试

pytest

许可证

MIT