mcp-vision-server

Один 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-эндпоинтов:

Вы также можете использовать любой другой 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: Вручную

Параметры инструмента (переопределяют окружение при каждом вызове): 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.