convez.ai
MCP ServerIntegração & APIsIntermediário
rongtianjie

Vision MCP Server

rongtianjie/vision_mcp

Adicione visão a qualquer LLM não-multimodal via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que estende LLMs sem capacidade multimodal (como DeepSeek) com visão computacional, integrando qualquer API compatível com OpenAI. Expõe a ferramenta `describe_image` para Claude Code, Cline e outros agentes AI analisarem imagens automaticamente.

Instalação

$npx convez-ai rongtianjie/vision_mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Analisar screenshots e extrair informações textuais de imagens
  • Descrever gráficos, tabelas e diagramas de arquitetura
  • Converter imagens de dados estruturados em markdown ou JSON
  • Diagnosticar erros visuais em logs e relatórios

Veredito

Solução prática para democratizar visão computacional em agentes que não têm suporte nativo. Configuração clara via `.env`, suporta múltiplos backends (SiliconFlow, vLLM, Ollama) e integração direta com Claude Code/Cline sem overhead de reconfiguração.

README

A tradução para o português deste README ainda está na fila.

Vision MCP Server

为缺少多模态能力的 LLM(如 DeepSeek)提供图片理解能力。通过 OpenAI-compatible API 将图片转发至视觉模型,以 MCP 工具形式暴露 describe_image,可接入任意支持 MCP 协议的 AI Agent(Claude Code、Cline、Continue.dev 等)。


一、配置方式

所有后端配置(API 地址、密钥、模型名)通过项目根目录的 .env 文件管理,无需在 MCP 注册时反复传入环境变量。修改配置后重启 Agent 即可生效。

1. 安装

uv venv && uv pip install -e .

2. 配置后端

复制配置模板并填入实际值:

cp .env.example .env

.env 文件内容:

VISION_API_BASE=https://api.siliconflow.cn/v1      # 视觉模型 API 地址
VISION_API_KEY=sk-your-key-here                      # API 密钥
VISION_MODEL=Qwen/Qwen3.6-35B-A3B                    # 模型名称
VISION_MAX_TOKENS=2000                                # 最大输出 token 数(可选)

.env 由 Server 启动时自动加载,修改后重启 Agent 即可生效,无需重新注册 MCP。

变量必填默认值说明
VISION_API_BASE是http://localhost:8000/v1API 地址,不含 /chat/completions 后缀
VISION_API_KEY按需not-neededAPI 密钥(本地部署留空即可)
VISION_MODEL是qwen-vl-plus视觉模型名称
VISION_MAX_TOKENS否2000单次响应最大 token 数

3. 注册到 AI Agent

方式 A(推荐)— 直接使用 .mcp.json

项目已内置 .mcp.json 文件,支持此格式的 Agent(Cline、Continue.dev 等)会自动识别:

{
  "mcpServers": {
    "vision": {
      "command": "uv",
      "args": ["run", "vision-mcp"]
    }
  }
}

方式 B — Claude Code 手动注册

claude mcp add-json -s user vision '{
  "command": "uv",
  "args": ["run", "vision-mcp"]
}'

所有方式均无需携带 env 字段,配置已由 .env 文件管理。

4. 验证

vision-mcp --help

确认 Agent 中 MCP Server 状态为已连接(Claude Code: claude mcp list → vision: vision-mcp - ✓ Connected)。


二、工作原理

User: "看看这张截图"
  → AI Agent (DeepSeek, 无视觉)
    → 调用 describe_image 工具
      → Vision MCP Server: 读取本地图片 → Base64 → POST 视觉模型 API
        ← 返回文字描述
  → AI Agent 基于描述回答用户

三、工具说明

describe_image — 理解图片内容

参数必填类型说明
image_path是string图片本地绝对路径
prompt否string描述侧重,如 "提取所有文字"、"描述图表趋势"
max_tokens否int覆盖环境变量 VISION_MAX_TOKENS,按需控制输出长度
  • 支持格式:PNG / JPG / JPEG / GIF / WebP / BMP
  • 单文件限制:≤ 20 MB

vision_ping — 诊断连通性

返回服务器状态信息,用于排查 MCP 通信是否正常。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",\
  "params":{"name":"vision_ping","arguments":{"msg":"hello"}}}' | vision-mcp

四、使用示例

User: 看看 @error_screenshot.png 里的报错信息
User: 分析 @architecture.png 的系统设计有什么问题
User: 把 @data_table.png 转成 markdown 表格
User: @chart.png 描述数据变化趋势,控制在 200 字以内

五、更新配置

修改 .env 文件后重启 AI Agent 即可生效,无需重新注册 MCP。

如需更换 Provider 的 API 地址,可参考以下配置:

ProviderVISION_API_BASE推荐 VISION_MODEL
SiliconFlowhttps://api.siliconflow.cn/v1Qwen/Qwen3.6-35B-A3B
本地 vLLMhttp://10.0.0.5:8000/v1Qwen3-VL-32B-Instruct
本地 Ollamahttp://localhost:11434/v1llava:13b
One-API 网关https://your-gateway.com/v1gpt-4o

常见问题

Failed to connect?

  1. 确认 vision-mcp --help 可执行
  2. 检查 API 连通性:curl $VISION_API_BASE/models
  3. 运行 vision-mcp 查看 stderr 日志

返回乱码或空内容?

  • 尝试将图片转为 PNG 格式
  • 缩小图片尺寸(Base64 后体积增大约 33%)
  • 更换更强大的视觉模型

图片数据会留存吗?

不会。图片仅通过 Base64 编码后 HTTPS 发送至视觉 API,Server 不做本地存储或缓存。使用公网 API 时注意勿传入敏感图片。

Ver o original no GitHub

Bom para

Relacionados