Skip to main content
Glama
deeneskoruzh
RuyimgByCN

mcp-vision-server

by RuyimgByCN
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-vision-server

PyPI Python License MCP

Один MCP-сервер для любой OpenAI-совместимой vision-модели.

Настройте один раз и используйте один и тот же инструмент analyze_image с OpenAI, OpenRouter, Zhipu, Bailian, SiliconFlow и другими совместимыми провайдерами. Он работает с Claude Code, Codex, Cursor, Zed и любым другим MCP-клиентом.

Зачем использовать mcp-vision-server?

  • ✅ Работает с любым MCP-клиентом – Claude Code, Codex, Cursor, Zed и другими.

  • ✅ Работает со многими провайдерами – меняйте провайдеров без изменения промптов или вызовов инструментов.

  • ✅ Один унифицированный API – один инструмент (analyze_image) для любого OpenAI-совместимого vision-эндпоинта.

  • ✅ Гибкий ввод изображений – URL, локальный файл или Base64 определяются автоматически.

  • ✅ Переопределение где угодно – глобальная настройка через переменные окружения или для каждого запроса.

Related MCP server: vision-mcp

Быстрый старт

  1. Установите сервер.

  2. Укажите вашего провайдера и API-ключ.

  3. Добавьте MCP-сервер в ваш клиент.

  4. Спросите:

Describe this screenshot.

Если всё настроено правильно, ваш MCP-клиент автоматически вызовет analyze_image и вернёт ответ vision-модели.

Возможности

  • Единый инструмент 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-совместимому vision-провайдеру и возвращает ответ в виде обычного текста вашему MCP-клиенту.

Провайдеры

Встроенные пресеты упрощают использование распространённых OpenAI-совместимых vision-эндпоинтов:

Провайдер

Пресет

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

Вы также можете использовать любой другой OpenAI-совместимый vision-эндпоинт, задав VISION_BASE_URL, VISION_API_KEY и VISION_MODEL вручную.

Установка и запуск

Требуется 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

Часто задаваемые вопросы

Почему бы не вызывать vision-провайдера напрямую?

Этот сервер предоставляет MCP-клиентам единый переиспользуемый vision-инструмент. Вы можете менять провайдеров без изменения клиентских промптов, имён MCP-инструментов или клиентского интеграционного кода.

Можно ли использовать провайдера, которого нет в списке?

Да. Используйте ручную настройку с VISION_BASE_URL, VISION_API_KEY и VISION_MODEL для любого OpenAI-совместимого vision-эндпоинта.

Можно ли переопределить провайдера для отдельного запроса?

Да. Используйте параметры инструмента 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-совместимые vision-эндпоинты.

  • Добавить более подробные примеры для Claude Code, Codex, Cursor и других MCP-клиентов.

  • Добавить опциональную поддержку потоковых ответов, если это улучшит UX 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYes
modelNo
promptNo请详细描述这张图片。
api_keyNo
base_urlNo
providerNo
image_typeNoauto
max_tokensNo
temperatureNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It states the tool can 'analyze' an image but does not reveal that it likely calls an external API (implied by parameters like api_key, base_url, provider), nor does it describe side effects, idempotency, or return behavior beyond the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two sentences summarizing purpose and use cases. It is front-loaded and wastes no words. However, it could be slightly more structured (e.g., separate parameter notes) to improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, output schema exists, sibling tool), the description is incomplete. It lacks parameter guidance, input/output format details, and prerequisites (e.g., API key requirements). The output schema exists but is not referenced. The description should provide more context for accurate invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description provides no explanation for any of the 9 parameters (image, model, prompt, api_key, base_url, provider, image_type, max_tokens, temperature). It fails to add meaning beyond the schema, leaving the agent to guess parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze or understand an image.' It provides specific use cases (image understanding, screenshot analysis, OCR, visual Q&A, UI restoration) which distinguishes it from the sibling tool 'list_providers' and gives a precise verb-resource relationship.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists when to use the tool (e.g., when image understanding or OCR is needed) and implies a specific context. However, it does not mention when not to use it or suggest alternative tools, which would improve guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_providersA

List all supported provider presets as a JSON array.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states output format but omits any behavioral details like performance, rate limits, or data freshness. However, for a simple parameterless list tool, the minimal description is somewhat adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence that is front-loaded with the key action and resource. Every word earns its place, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema is present, the description is nearly sufficient. However, it does not elaborate on what 'provider presets' entail, which could be slightly ambiguous. The completeness is high but not perfect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the description adds no information beyond the empty schema. According to the rubric, 0 params has a baseline score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List', the resource 'all supported provider presets', and the output format 'as a JSON array'. It effectively distinguishes from the only sibling tool 'analyze_image'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit when-to-use or alternatives are given, the context with only one sibling tool 'analyze_image' makes the usage obvious. The description lacks exclusion criteria but remains clear for this simple tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.1
    • First observedanalyze_image
    • First observedlist_providers
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • vision-mcp

    menoxz
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for analyzing images using multiple vision LLM providers (OpenCode, OpenAI, Anthropic, Google, and custom OpenAI-compatible endpoints). Provides tools to analyze single or multiple images, list providers, and test vision capabilities.
    MIT

  • mcp-six-eyes

    RimunAce
    A
    license
    A
    quality
    A
    maintenance
    MCP server that gives text-only AI agents the ability to understand images via vision tools, including multi-image analysis, OCR, comparison, and structured extraction. It uses providers like OpenAI, Anthropic, Gemini, and OpenRouter to return plain text descriptions.
    10
    7 npm
    MIT