Skip to main content
Glama

👁️ 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

目录

Related MCP server: glm-vision-mcp

特性

  • 三模态理解:图片 / 视频 / 文件(PDF、文本等)一次提问,纯文本返回

  • 本地图片免上传:传本地路径自动转 base64,无需公网 URL;视频/文件模态接受公网 URL

  • 思考模式:可选开启(thinking=true),适合需要深度推理的视觉任务

  • 健壮性:3 次指数退避重试(429 / 5xx / 超时)、60s 超时、结构化错误返回(绝不向 Agent 抛未处理异常)

  • 标准 MCP(stdio):兼容 Claude Code / Cursor / Cline / Continue / Windsurf / Claude Desktop / Reasonix 等任何 MCP 客户端

  • 零成本:基于智谱免费模型,无需充值

架构设计

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

快速开始

① 安装

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

② 配置 Key

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

Key 免费申请:登录智谱开放平台 → 个人中心 → API Keys。

③ 注册到 Agent(项目根目录创建 .mcp.json)

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

④ 提问

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

各 Agent 的详细注册方式与常见问题见下文 安装与部署。

安装与部署

1. 前置条件

项目

要求

Python

≥ 3.10(Windows / macOS / Linux 均可)

智谱 API Key

免费申请:登录智谱开放平台 → 个人中心 → API Keys(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.2.0-py3-none-any.whl"

升级版本后,请同步把 URL 中的 0.2.0 替换为新版本号。

国内网络下载依赖较慢时加镜像源(wheel 本体仍从 GitHub 拉取,只有依赖走镜像):

pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.2.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.2.0

  2. 在 Assets 区下载 deepseek_vision_mcp-0.2.0-py3-none-any.whl

  3. 本地安装:pip install deepseek_vision_mcp-0.2.0-py3-none-any.whl

方式 C:源码包(sdist,含 skills/ 决策层文件与测试)

下载 deepseek_vision_mcp-0.2.0.tar.gz 后:pip install deepseek_vision_mcp-0.2.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。

工具与使用示例

工具

说明

关键参数

vision_analyze_image

图片理解(本地路径或 URL)

source、question、thinking

vision_analyze_video

视频理解(仅公网 URL)

source、question、thinking

vision_analyze_file

文件理解(仅公网 URL,PDF/文本等)

source、question、thinking

示例:让 Agent「描述这张图片」后,工具返回统一 JSON 结构:

{
  "ok": true,
  "content": "图片中是一个深蓝色背景的 Logo,上面有白色文字……",
  "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、INTERNAL 等。

测试

pytest

注意事项

  • GLM-4.6V-Flash 不支持同时理解多种模态(图片/视频/文件一次只传一种)——Skill 层已约束

  • 视频/文件模态要求可访问的公网 URL(本地文件需先上传到可访问位置);仅图片支持本地路径

  • .env 已加入 .gitignore,API Key 永不入库

  • 本包目前通过 GitHub Release 分发(未发布到 PyPI)

许可证

MIT © 2026 Jun Hua

Available Tools

3 tools
vision_analyze_fileA

分析一个文档文件(PDF / 文本等)并回答问题。source 仅支持公网可访问的文件 URL; 本地文件请先上传到可访问地址。question 为对文档的提问;thinking=True 开启深度思考。 返回 JSON:{ok, content, thinking, usage} 或 {ok:false, error:{code,message}}。

Inputs: source (required), question (required), thinking. Returns: result

vision_analyze_imageA

分析一张图片并回答问题。source 为本地图片路径(自动转 base64)或公网 URL; question 为对图片的提问;thinking=True 开启深度思考模式(更慢但更深入)。 返回 JSON:{ok, content, thinking, usage} 或 {ok:false, error:{code,message}}。

Inputs: source (required), question (required), thinking. Returns: result

vision_analyze_videoA

分析一段视频并回答问题。source 仅支持公网可访问的视频 URL(如 https://...); 本地视频请先上传到可访问地址。question 为对视频的提问;thinking=True 开启深度思考。 返回 JSON:{ok, content, thinking, usage} 或 {ok:false, error:{code,message}}。

Inputs: source (required), question (required), thinking. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct media type: image, video, and document file. The purpose of each is clearly separated by the input format, leaving no ambiguity about which tool to use for a given source.

    Naming Consistency5/5

    All tools follow the consistent pattern `vision_analyze_<type>`, making it easy to predict the tool name for new media types. The verb `analyze` and prefix `vision_` are used uniformly.

    Tool Count5/5

    Three tools cover the core capabilities of the server (image, video, and document analysis) without unnecessary bloat. This is a well-scoped set for a vision-focused server.

    Completeness4/5

    The set covers the primary media types (image, video, document), but local video and file inputs require public URLs, which could be a usability gap. Missing audio analysis is a minor omission but not core to vision.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Multi-model vision understanding MCP server that provides unified image analysis for AI assistants without native vision, supporting models like GLM-4.6V, DeepSeek-OCR, Qwen3-VL-Flash, and more.
      1
      512 npm
      116
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that gives text-only models vision capabilities via free GLM vision models, supporting image description, OCR, chart/document analysis, and grounding with automatic model fallback.
      1
      -