Skip to main content
Glama

mcp-vision-server

PyPI Python License MCP

一个适用于所有 OpenAI 兼容视觉模型的 MCP 服务器。

配置一次,即可在 OpenAI、OpenRouter、Zhipu、Bailian、SiliconFlow 等兼容提供商中使用同一个 analyze_image 工具。它适用于 Claude Code、Codex、Cursor、Zed 以及任何其他 MCP 客户端。

为什么使用 mcp-vision-server?

  • ✅ 适用于任何 MCP 客户端 – Claude Code、Codex、Cursor、Zed 等。

  • ✅ 支持众多提供商 – 切换提供商时无需更改提示或工具调用。

  • ✅ 统一 API – 一个工具(analyze_image)即可用于所有 OpenAI 兼容视觉端点。

  • ✅ 灵活的图片输入 – 自动识别 URL、本地文件或 Base64。

  • ✅ 随处覆盖 – 可通过环境变量进行全局配置,或按请求单独配置。

Related MCP server: vision-mcp

快速开始

  1. 安装服务器。

  2. 设置你的提供商和 API 密钥。

  3. 将 MCP 服务器添加到你的客户端。

  4. 提问:

Describe this screenshot.

如果一切配置正确,你的 MCP 客户端将自动调用 analyze_image 并返回视觉模型的响应。

功能特性

  • 单个 analyze_image 工具,接口一致。

  • 支持 URL、本地文件和 Base64 图片输入。

  • 内置 13 个提供商预设。

  • 通过 VISION_PROVIDER 或 provider 参数选择提供商。

  • 支持环境级别和请求级别的配置覆盖。

示例

让你的 MCP 客户端分析一张图片:

Analyze this screenshot and tell me what UI is shown.

客户端调用 MCP 工具:

{
  "tool": "analyze_image",
  "arguments": {
    "image": "/path/to/screenshot.png",
    "prompt": "Analyze this screenshot and tell me what UI is shown."
  }
}

服务器对图片输入进行标准化,将其发送到所选 OpenAI 兼容视觉提供商,并将纯文本答案返回给你的 MCP 客户端。

提供商

内置预设让常见的 OpenAI 兼容视觉端点易于使用:

提供商

预设

Zhipu

zhipu

Bailian / DashScope

bailian

OpenAI

openai

SiliconFlow

siliconflow

OpenRouter

openrouter

Ark / Volcengine

ark

StepFun

stepfun

Kimi / Moonshot

kimi

MiniMax

minimax

ModelScope

modelscope

NVIDIA NIM

nvidia

Novita AI

novita

你也可以通过手动设置 VISION_BASE_URL、VISION_API_KEY 和 VISION_MODEL 来使用任何其他 OpenAI 兼容视觉端点。

安装与运行

需要 Python ≥ 3.10 和 uv。

cd mcp-vision-server
uv sync                  # install deps
uv run pytest -v         # run tests
uv run ruff check .      # lint
uv run mcp-vision-server # start stdio server

配置

选项 1:提供商预设(推荐)

export VISION_PROVIDER=zhipu     # default
export VISION_API_KEY=your_key

完整预设列表请参阅 提供商。

你也可以使用提供商特定的环境变量(例如 DASHSCOPE_API_KEY、OPENAI_API_KEY)作为回退。

选项 2:手动配置

变量

必填

描述

VISION_API_KEY

是

API 密钥

VISION_BASE_URL

否

OpenAI 兼容端点

VISION_MODEL

否

模型名称

工具参数(每次调用覆盖环境变量):image、prompt、image_type、provider、base_url、api_key、model、temperature、max_tokens。

MCP 客户端设置

Claude Code (.mcp.json)

{
  "mcpServers": {
    "vision": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"],
      "env": {
        "VISION_PROVIDER": "zhipu",
        "VISION_API_KEY": "your_key"
      }
    }
  }
}

Claude Code 插件

# After PyPI publish
claude plugins install RuyimgByCN/mcp-vision-server

# Local test
claude plugins install /path/to/mcp-vision-server

该仓库包含一个 .claude-plugin.json 清单文件——claude plugins install 会自动读取它。

Codex (OpenAI Codex CLI)

编辑 ~/.codex/config.toml:

[mcp_servers.vision]
command = "uvx"
args = ["mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }

或者用于本地开发:

[mcp_servers.vision]
command = "uv"
args = ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }

Cursor / 其他 uvx 客户端

将 command 替换为 uvx,将 args 替换为 ["--from", "/path/to/mcp-vision-server", "mcp-vision-server"],env 保持不变。

提供商示例

// Bailian
"env": { "VISION_PROVIDER": "bailian", "VISION_API_KEY": "your_key" }

// OpenAI
"env": { "VISION_PROVIDER": "openai", "VISION_API_KEY": "sk-xxx" }

// Fully custom
"env": {
  "VISION_BASE_URL": "https://your-endpoint/v1",
  "VISION_API_KEY": "your_key",
  "VISION_MODEL": "your-model"
}

架构

MCP Client (Claude Code / Codex / Cursor / Zed)
        │
        ▼
mcp-vision-server
        │
        ├── mcp_vision_server/server.py     # MCP tool entrypoints
        ├── mcp_vision_server/config.py     # env/provider/parameter resolution
        ├── mcp_vision_server/image.py      # URL/file/base64 normalization
        └── mcp_vision_server/providers.py  # provider presets
        │
        ▼
OpenAI-compatible Vision API
        │
        ▼
Vision model response

常见问题

为什么不直接调用视觉提供商?

该服务器为 MCP 客户端提供了一个可复用的统一视觉工具。你可以在不更改客户端提示、MCP 工具名称或客户端集成代码的情况下切换提供商。

我能否使用未列出的提供商?

可以。对于任何 OpenAI 兼容视觉端点,使用 VISION_BASE_URL、VISION_API_KEY 和 VISION_MODEL 进行手动配置即可。

我能否按请求覆盖提供商?

可以。使用 provider、base_url、api_key 或 model 工具参数,可在单次调用中覆盖环境级别的配置。

支持哪些图片格式?

服务器接受图片 URL、本地文件路径和 Base64 字符串。输入类型可以自动检测,也可以通过 image_type 指定。

开发

uv sync --all-groups
uv run ruff check .
uv run ruff format .
uv run pytest -v
uv build
uv run twine check dist/*

发布清单

  1. 更新 pyproject.toml 中的版本号。

  2. 运行 uv run ruff check .、uv run pytest -v、uv build 和 uv run twine check dist/*。

  3. 创建并推送版本标签,例如 v0.1.2。

  4. 让 GitHub Actions 通过可信发布将包发布到 PyPI。

路线图

  • 当稳定的 OpenAI 兼容视觉端点可用时,添加更多提供商预设。

  • 为 Claude Code、Codex、Cursor 和其他 MCP 客户端添加更丰富的示例。

  • 如果 MCP 客户端用户体验能从中受益,添加可选的流式响应支持。

  • 仅在提供商需要自定义请求逻辑时,将提供商特定行为拆分为插件。

关于

作者: RuyimgByCN

许可证: 仅限个人使用。禁止商用——详见 LICENSE。商业授权请联系作者。

中文说明: 个人使用免费,禁止商用。商业授权请联系作者。详见 README_ZH.md。

Available Tools

2 tools
analyze_imageB

Analyze or understand an image.

Use this tool when an MCP client needs image understanding, screenshot analysis, OCR-like text recognition, visual Q&A, or UI restoration.

Inputs: image (required), model, prompt, api_key, +5 more. Returns: result

list_providersA

List all supported provider presets as a JSON array.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have entirely distinct purposes: analyze_image for image understanding and list_providers for listing provider presets. No overlap or ambiguity.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern (analyze_image, list_providers), making naming predictable and clear.

    Tool Count3/5

    Only two tools for a vision server feels slightly thin. While the count is not extreme, it borders on insufficient for typical vision tasks.

    Completeness2/5

    The server covers only basic image analysis and a provider listing, missing common vision operations like generation, manipulation, or filtering. The tool surface is significantly incomplete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers