mcp-vision-server

Un servidor MCP para cada modelo de visión compatible con OpenAI.

Configúralo una vez y usa la misma herramienta analyze_image con OpenAI, OpenRouter, Zhipu, Bailian, SiliconFlow y otros proveedores compatibles. Funciona con Claude Code, Codex, Cursor, Zed y cualquier otro cliente MCP.

¿Por qué usar mcp-vision-server?

• ✅ Funciona con cualquier cliente MCP – Claude Code, Codex, Cursor, Zed y más.

• ✅ Funciona con muchos proveedores – cambia de proveedor sin modificar prompts ni llamadas a herramientas.

• ✅ Una API unificada – una sola herramienta (analyze_image) para cada endpoint de visión compatible con OpenAI.

• ✅ Entrada de imagen flexible – URL, archivo local o Base64 se detectan automáticamente.

• ✅ Anulación en cualquier lugar – configura globalmente con variables de entorno o por solicitud.

Related MCP server: vision-mcp

Inicio rápido

1. Instala el servidor.

2. Configura tu proveedor y clave de API.

3. Añade el servidor MCP a tu cliente.

4. Pregunta:

Describe this screenshot.

Si todo está configurado correctamente, tu cliente MCP llamará automáticamente a analyze_image y devolverá la respuesta del modelo de visión.

Características

• Herramienta única analyze_image con una interfaz consistente.

• Admite entradas de imagen por URL, archivo local y Base64.

• Admite 13 ajustes predefinidos de proveedores integrados.

• Selección de proveedor mediante VISION_PROVIDER o el parámetro provider.

• Anulaciones de configuración a nivel de entorno y de solicitud.

Ejemplo

Pide a tu cliente MCP que analice una imagen:

Analyze this screenshot and tell me what UI is shown.

El cliente llama a la herramienta MCP:

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

El servidor normaliza la entrada de imagen, la envía al proveedor de visión compatible con OpenAI seleccionado y devuelve una respuesta de texto plano a tu cliente MCP.

Proveedores

Los ajustes predefinidos integrados facilitan el uso de endpoints de visión compatibles con OpenAI:

También puedes usar cualquier otro endpoint de visión compatible con OpenAI configurando manualmente VISION_BASE_URL, VISION_API_KEY y VISION_MODEL.

Instalación y ejecución

Requiere Python ≥ 3.10 y 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

Configuración

Opción 1: Ajuste predefinido de proveedor (recomendado)

export VISION_PROVIDER=zhipu     # default
export VISION_API_KEY=your_key

Consulta Proveedores para ver la lista completa de ajustes predefinidos.

También puedes usar variables de entorno específicas del proveedor (por ejemplo, DASHSCOPE_API_KEY, OPENAI_API_KEY) como respaldo.

Opción 2: Manual

Parámetros de la herramienta (anulan el entorno por llamada): image, prompt, image_type, provider, base_url, api_key, model, temperature, max_tokens.

Configuración del cliente 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"
      }
    }
  }
}

Complemento de Claude Code

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

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

El repositorio incluye un manifiesto .claude-plugin.json — claude plugins install lo lee automáticamente.

Codex (OpenAI Codex CLI)

Edita ~/.codex/config.toml:

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

O para desarrollo local:

[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 / otros clientes uvx

Reemplaza command por uvx, args por ["--from", "/path/to/mcp-vision-server", "mcp-vision-server"], mismo env.

Ejemplos de proveedores

// 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"
}

Arquitectura

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

Preguntas frecuentes

¿Por qué no llamar directamente al proveedor de visión?

Este servidor ofrece a los clientes MCP una herramienta de visión única y reutilizable. Puedes cambiar de proveedor sin modificar los prompts del cliente, los nombres de las herramientas MCP ni el código de integración del lado del cliente.

¿Puedo usar un proveedor que no esté en la lista?

Sí. Usa la configuración manual con VISION_BASE_URL, VISION_API_KEY y VISION_MODEL para cualquier endpoint de visión compatible con OpenAI.

¿Puedo anular el proveedor por solicitud?

Sí. Usa los parámetros de la herramienta provider, base_url, api_key o model para anular la configuración a nivel de entorno en una sola llamada.

¿Qué formatos de imagen se admiten?

El servidor acepta URLs de imagen, rutas de archivo locales y cadenas Base64. El tipo de entrada se puede detectar automáticamente o especificarse con image_type.

Desarrollo

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

Lista de verificación para publicar

1. Actualiza la versión en pyproject.toml.

2. Ejecuta uv run ruff check ., uv run pytest -v, uv build y uv run twine check dist/*.

3. Crea y envía una etiqueta de versión, por ejemplo v0.1.2.

4. Deja que GitHub Actions publique en PyPI mediante publicación de confianza.

Hoja de ruta

• Añadir más ajustes predefinidos de proveedores cuando haya endpoints de visión compatibles con OpenAI estables.

• Añadir ejemplos más completos para Claude Code, Codex, Cursor y otros clientes MCP.

• Añadir soporte opcional de respuestas en streaming si la experiencia de usuario del cliente MCP se beneficia.

• Dividir el comportamiento específico de cada proveedor en complementos solo cuando los proveedores requieran lógica de solicitud personalizada.

Acerca de

Autor: RuyimgByCN

Licencia: Solo uso personal. Prohibido uso comercial — consulta LICENSE para más detalles. Contacta con el autor para licencias comerciales.

Nota en chino: Uso personal gratuito, prohibido uso comercial. Para licencia comercial contacta con el autor. Ver README_ZH.md.