Vision MCP Server

Ein Model Context Protocol (MCP)-Server, der Agenten, die mit nicht-multimodalen Modellen verbunden sind, Bildverständnis verleiht (DeepSeek, ältere GPT-4, lokale kleine Modelle usw.): Der Agent übergibt ein Bild an das MCP-Tool, der Server ruft ein Vision-Modell auf und gibt Text zurück.

Unterstützt große Anbieter in China und den USA sowie jeden OpenAI-kompatiblen Endpunkt. Offizielle SDKs zuerst, Abstraktion vor Implementierung, nicht-invasive Anbietererweiterungen.

中文文档见 README.zh-CN.md

Funktionen

• 4 Tools: analyze_image / describe_image / ocr_image / list_providers, alle geben reinen Markdown-Text zurück

• 13 integrierte Anbieter: OpenAI / Anthropic / Google Gemini / Qwen (DashScope) / Zhipu / Doubao (Volcengine) / ERNIE (Qianfan) / StepFun / Ollama / Alibaba Bailian / SiliconFlow / OpenRouter / benutzerdefinierter OpenAI-kompatibler Endpunkt

• Drei Bildeingaben: lokaler Pfad / http(s)-URL / base64 (data-URI oder rohes base64), automatisch erkannt

• Dreistufige Fallback-Kette: offizielles SDK → OpenAI-kompatibler Endpunkt → natives fetch (siehe SPEC §1)

• Zustandslos: Jeder Aufruf ist unabhängig; Bilder und Ergebnisse werden nie gecacht; Schlüssel werden nur aus Umgebungsvariablen gelesen

Related MCP server: vision-mcp

Schnellstart

Option A: npx (auf npm veröffentlicht, kein Repo nötig)

npx -y @inferai/vision-mcp

Option B: lokaler Build

git clone <repo> && cd vision-mcp
pnpm install
pnpm build
node dist/index.js

MCP-Konfigurationsbeispiele (stdio)

Der Server spricht den stdio-Transport: Der MCP-Client startet den Prozess und tauscht JSON-RPC-Nachrichten über stdin/stdout aus. Konfigurieren Sie ihn dort, wo Ihr Client MCP-Server definiert:

• Claude Code: projektweite .mcp.json oder benutzerweite ~/.claude.json (mcpServers-Schlüssel)

• Claude Desktop: claude_desktop_config.json

• Jeder MCP-Client (Cursor, selbstgebaute Agenten usw.): gleiche Struktur

npx-Version (verfügbar, nachdem das Paket veröffentlicht wurde):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@inferai/vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

Lokale Entwicklung (Pfad anpassen; --env-file-if-exists=.env lädt .env nativ):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["--env-file-if-exists=.env", "/absolute/path/to/vision-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Mit Startargumenten (Anbieter-Standardwerte per argv überschreiben, siehe unten):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@inferai/vision-mcp",
        "--default-provider=dashscope",
        "--siliconflow-api-key=sk-...",
        "--siliconflow-model=Qwen/Qwen2.5-VL-7B-Instruct"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

stdio-Hinweise:

• stdout transportiert nur das MCP-Protokoll — der Server gibt dort nie Logs aus; Diagnosen gehen an stderr

• der Client verwaltet den Prozesslebenszyklus (Start beim Start, Beenden beim Exit); kein Daemon nötig

• der erste npx-Lauf lädt das Paket herunter und kann einige Sekunden dauern

• Umgebungsvariablen können auch aus der Shell-Umgebung stammen, wenn der Client diese erbt (kein env-Block nötig)

Debuggen mit MCP Inspector:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js --xxx-api-key=xxx --xxx2-api-key=xxx

Variablen setzen

1. env-Block in der MCP-Konfiguration (empfohlen, am zuverlässigsten plattformübergreifend) — schreiben Sie die Variablen in das env-Objekt oben

2. .env-Datei (lokale Entwicklung) — kopieren Sie .env.example nach .env, füllen Sie sie aus, dann node --env-file-if-exists=.env dist/index.js (Node 22 nativ, kein dotenv nötig)

3. Shell-Export — export OPENAI_API_KEY=sk-xxx und dann ausführen

Anbieter ohne Schlüssel erscheinen in list_providers als nicht verfügbar und melden die fehlende Variable beim Aufruf.

Veröffentlichung (bevor npx funktioniert)

pnpm publish          # or pnpm release (changeset flow)

Umgebungsvariablen

API_KEY, BASE_URL und MODEL jedes Anbieters unterstützen Umgebungs-Overrides (Konvention: <PROVIDER_PREFIX>_API_KEY / <PROVIDER_PREFIX>_BASE_URL / <PROVIDER_PREFIX>_MODEL):

? = optional (hat einen integrierten Standard); * = erforderlich.

Globale Konfiguration:

Fallback-Kette

Wenn mehrere Anbieter verfügbar sind, durchlaufen Aufrufe die Prioritätskette: konfigurierter Standard → VISION_MCP_PROVIDER_PRIORITY-Liste → Tabellenreihenfolge (nicht verfügbare Anbieter werden übersprungen).

• jeder Anbieter wird bei Anbieterfehlern (Upstream-Fehler, Timeouts) bis zu VISION_MCP_MAX_RETRIES-mal erneut versucht

• nachdem ein Anbieter seine Wiederholungen erschöpft hat, wird der nächste verfügbare Anbieter in der Kette versucht, bis zu VISION_MCP_MAX_FALLBACKS Fallbacks

• nur Anbieterfehler lösen Wiederholung/Fallback aus; Konfigurations- oder Bildfehler schlagen sofort fehl

• ein explizit angefordertes provider-Argument wird allein versucht (kein Fallback)

• wenn alles fehlschlägt, listet der Fehler jeden versuchten Anbieter und dessen letzten Fehler auf

Auch als argv verfügbar: --provider-priority=..., --max-retries=N, --max-fallbacks=N (überschreiben Umgebungsvariablen).

MCP-Startargumente (argv)

apiKey / baseUrl / model jedes Anbieters können über Startargumente überschrieben werden (höhere Priorität als Umgebungsvariablen), Format --<provider>-<field>:

node dist/index.js \
  --openai-api-key=sk-xxx \
  --openai-base-url=https://my-gateway.example.com/v1 \
  --openai-model=gpt-4o-mini \
  --dashscope-api-key=sk-xxx \
  --default-provider=dashscope

• Global: --default-provider <name> / --default-model <name>

• Pro Anbieter: --<provider>-api-key, --<provider>-base-url, --<provider>-model (Gleichheits- oder Leerzeichenform funktionieren beide)

• Jeder OpenAI-kompatible Drittanbieterdienst: in einer Zeile mit --openai-compat-base-url + --openai-compat-api-key + --openai-compat-model verbinden; oder base-url eines beliebigen integrierten Anbieters auf einen Mirror/Proxy zeigen lassen

Priorität: Tool-Argumente provider/model > Startargumente (pro Anbieter > globaler Standard) > Umgebungsvariablen > integrierte Anbieter-Standardwerte.

Tools

image akzeptiert: lokalen Pfad / http(s)://-URL / data:-URI / rohes base64, automatisch erkannt.

Sicherheitshinweis: URL-Downloads sind SSRF-geschützt — jeder Hop (einschließlich Weiterleitungen) wird validiert und URLs, die auf Loopback-, private oder Link-Local-Adressen auflösen, werden blockiert (ein Hinweis im Fehler erklärt warum).

Anbieterintegration (dreistufige Fallback-Kette)

Einen Anbieter hinzufügen: Für OpenAI-kompatible Endpunkte fügen Sie eine Zeile zu RULES in src/core/config.ts hinzu plus ein Mapping in der Factory-Tabelle in src/index.ts — kein neuer Code. Für Implementierungen mit offiziellem SDK oder nativem fetch: siehe SPEC §1.

Entwicklung

pnpm check        # biome checks
pnpm test         # rstest unit tests (injected mocks, no network)
pnpm build        # rslib build

Echtaufruf-Smoke-Tests (werden nur gegen Anbieter ausgeführt, deren Schlüssel konfiguriert sind; andernfalls übersprungen):

OPENAI_API_KEY=sk-... pnpm exec rstest tests/e2e

Architektur

src/
├── index.ts            # Entry: composition root, stdio startup
├── core/               # Abstraction: interfaces / image loading / config / registry
├── providers/          # Adapters: official SDK or compatible endpoints, protocol conversion only
└── server/tools.ts     # MCP tool layer: zod validation + error mapping

Vollständige Spezifikation: SPEC.md.