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

Ein MCP-Server für jedes OpenAI-kompatible Vision-Modell.

Einmal konfigurieren und dasselbe analyze_image-Tool über OpenAI, OpenRouter, Zhipu, Bailian, SiliconFlow und andere kompatible Anbieter verwenden. Es funktioniert mit Claude Code, Codex, Cursor, Zed und jedem anderen MCP-Client.

Warum mcp-vision-server verwenden?

  • ✅ Funktioniert mit jedem MCP-Client – Claude Code, Codex, Cursor, Zed und mehr.

  • ✅ Funktioniert mit vielen Anbietern – Anbieter wechseln, ohne Prompts oder Tool-Aufrufe zu ändern.

  • ✅ Eine einheitliche API – ein Tool (analyze_image) für jeden OpenAI-kompatiblen Vision-Endpunkt.

  • ✅ Flexible Bildeingabe – URL, lokale Datei oder Base64 werden automatisch erkannt.

  • ✅ Überall überschreibbar – global mit Umgebungsvariablen oder pro Anfrage konfigurierbar.

Related MCP server: vision-mcp

Schnellstart

  1. Installieren Sie den Server.

  2. Legen Sie Ihren Anbieter und API-Schlüssel fest.

  3. Fügen Sie den MCP-Server zu Ihrem Client hinzu.

  4. Fragen Sie:

Describe this screenshot.

Wenn alles korrekt konfiguriert ist, ruft Ihr MCP-Client automatisch analyze_image auf und gibt die Antwort des Vision-Modells zurück.

Funktionen

  • Ein einziges analyze_image-Tool mit einer konsistenten Schnittstelle.

  • Unterstützt URL-, lokale Datei- und Base64-Bildeingaben.

  • Unterstützt 13 integrierte Anbieter-Voreinstellungen.

  • Anbieterauswahl über VISION_PROVIDER oder den Parameter provider.

  • Überschreibungen auf Umgebungs- und Anfrageebene.

Beispiel

Bitten Sie Ihren MCP-Client, ein Bild zu analysieren:

Analyze this screenshot and tell me what UI is shown.

Der Client ruft das MCP-Tool auf:

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

Der Server normalisiert die Bildeingabe, sendet sie an den ausgewählten OpenAI-kompatiblen Vision-Anbieter und gibt eine Klartextantwort an Ihren MCP-Client zurück.

Anbieter

Integrierte Voreinstellungen machen gängige OpenAI-kompatible Vision-Endpunkte einfach nutzbar:

Anbieter

Voreinstellung

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

Sie können auch jeden anderen OpenAI-kompatiblen Vision-Endpunkt verwenden, indem Sie VISION_BASE_URL, VISION_API_KEY und VISION_MODEL manuell festlegen.

Installation & Ausführung

Erfordert Python ≥ 3.10 und 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

Konfiguration

Option 1: Anbieter-Voreinstellung (empfohlen)

export VISION_PROVIDER=zhipu     # default
export VISION_API_KEY=your_key

Siehe Anbieter für die vollständige Liste der Voreinstellungen.

Sie können auch anbieterspezifische Umgebungsvariablen (z. B. DASHSCOPE_API_KEY, OPENAI_API_KEY) als Fallback verwenden.

Option 2: Manuell

Variable

Erforderlich

Beschreibung

VISION_API_KEY

Ja

API-Schlüssel

VISION_BASE_URL

Nein

OpenAI-kompatibler Endpunkt

VISION_MODEL

Nein

Modellname

Tool-Parameter (überschreiben Umgebung pro Aufruf): image, prompt, image_type, provider, base_url, api_key, model, temperature, max_tokens.

MCP-Client-Einrichtung

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-Plugin

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

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

Das Repository enthält ein .claude-plugin.json-Manifest – claude plugins install liest es automatisch.

Codex (OpenAI Codex CLI)

Bearbeiten Sie ~/.codex/config.toml:

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

Oder für die lokale Entwicklung:

[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 / andere uvx-Clients

Ersetzen Sie command durch uvx, args durch ["--from", "/path/to/mcp-vision-server", "mcp-vision-server"], gleiche env.

Anbieter-Beispiele

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

Architektur

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

FAQ

Warum nicht den Vision-Anbieter direkt aufrufen?

Dieser Server bietet MCP-Clients ein einziges, wiederverwendbares Vision-Tool. Sie können Anbieter wechseln, ohne Client-Prompts, MCP-Toolnamen oder clientseitigen Integrationscode zu ändern.

Kann ich einen Anbieter verwenden, der nicht aufgeführt ist?

Ja. Verwenden Sie die manuelle Konfiguration mit VISION_BASE_URL, VISION_API_KEY und VISION_MODEL für jeden OpenAI-kompatiblen Vision-Endpunkt.

Kann ich den Anbieter pro Anfrage überschreiben?

Ja. Verwenden Sie die Tool-Parameter provider, base_url, api_key oder model, um die Konfiguration auf Umgebungsebene für einen einzelnen Aufruf zu überschreiben.

Welche Bildformate werden unterstützt?

Der Server akzeptiert Bild-URLs, lokale Dateipfade und Base64-Strings. Der Eingabetyp kann automatisch erkannt oder mit image_type angegeben werden.

Entwicklung

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

Release-Checkliste

  1. Aktualisieren Sie die Version in pyproject.toml.

  2. Führen Sie uv run ruff check ., uv run pytest -v, uv build und uv run twine check dist/* aus.

  3. Erstellen und pushen Sie einen Versions-Tag, zum Beispiel v0.1.2.

  4. Lassen Sie GitHub Actions über Trusted Publishing auf PyPI veröffentlichen.

Roadmap

  • Weitere Anbieter-Voreinstellungen hinzufügen, sobald stabile OpenAI-kompatible Vision-Endpunkte verfügbar sind.

  • Umfangreichere Beispiele für Claude Code, Codex, Cursor und andere MCP-Clients hinzufügen.

  • Optionale Unterstützung für Streaming-Antworten hinzufügen, wenn die MCP-Client-UX davon profitiert.

  • Anbieterspezifisches Verhalten nur dann in Plugins aufteilen, wenn Anbieter eine benutzerdefinierte Anforderungslogik erfordern.

Über

Autor: RuyimgByCN

Lizenz: Nur für den persönlichen Gebrauch. Kommerzielle Nutzung ist untersagt – siehe LICENSE für Details. Kontaktieren Sie den Autor für kommerzielle Lizenzen.

中文说明： 个人使用免费，禁止商用。商业授权请联系作者。详见 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