Skip to main content
Glama
Sign In
deeneskoruzh
mcp-vision-server

mcp-vision-server

by RuyimgByCN
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-vision-server

PyPI Python License MCP

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:

Proveedor

Ajuste predefinido

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

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

Variable

¿Requerida?

Descripción

VISION_API_KEY

Sí

Clave de API

VISION_BASE_URL

No

Endpoint compatible con OpenAI

VISION_MODEL

No

Nombre del modelo

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.

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.

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

Output 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.

NameRequiredDescriptionDefault

No parameters

Output 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

ActivityInactive
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers