Vision MCP Server

非マルチモーダルモデル（DeepSeek、旧世代のGPT-4、ローカルの小規模モデルなど）に接続されたエージェントに視覚理解をもたらすModel Context Protocol（MCP）サーバーです。エージェントが画像をMCPツールに渡すと、サーバーが視覚モデルを呼び出し、テキストを返します。

中国と米国の主要プロバイダーに加え、任意のOpenAI互換エンドポイントをサポートします。公式SDKを最優先し、抽象化を実装に先立たせ、プロバイダー追加はゼロ侵入で行います。

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

特徴

• 4つのツール: analyze_image / describe_image / ocr_image / list_providers。すべてプレーンなMarkdownテキストを返します

• 13の組み込みプロバイダー: OpenAI / Anthropic / Google Gemini / Qwen（DashScope）/ Zhipu / Doubao（Volcengine）/ ERNIE（Qianfan）/ StepFun / Ollama / Alibaba Bailian / SiliconFlow / OpenRouter / カスタムOpenAI互換エンドポイント

• 3種類の画像入力: ローカルパス / http(s) URL / base64（data URIまたは生のbase64）。自動判別されます

• 3段階のフォールバックチェーン: 公式SDK → OpenAI互換エンドポイント → ネイティブfetch（SPEC §1参照）

• ステートレス: すべての呼び出しは独立しています。画像と結果は決してキャッシュされず、キーは環境変数からのみ読み取られます

Related MCP server: vision-mcp

クイックスタート

オプションA: npx（npmに公開済み、リポジトリ不要）

npx -y @inferai/vision-mcp

オプションB: ローカルビルド

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

MCP設定例（stdio）

サーバーはstdioトランスポートで通信します。MCPクライアントがプロセスを起動し、stdin/stdout経由でJSON-RPCメッセージを交換します。お使いのクライアントでMCPサーバーを定義している場所ならどこでも設定できます：

• Claude Code: プロジェクトレベルの.mcp.jsonまたはユーザーレベルの~/.claude.json（mcpServersキー）

• Claude Desktop: claude_desktop_config.json

• その他のMCPクライアント（Cursor、自作エージェントなど）: 同じ構造

npx版（パッケージ公開後に利用可能）：

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

ローカル開発（パスを調整してください。--env-file-if-exists=.envは.envをネイティブに読み込みます）：

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

起動引数付き（argvでプロバイダーのデフォルトを上書き、下記参照）：

{
  "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に関する注意：

• stdoutはMCPプロトコルのみを運びます。サーバーがログを出力することは決してなく、診断情報はstderrに送られます

• クライアントがプロセスのライフサイクルを管理します（起動時に生成、終了時に停止）。デーモンは不要です

• 初回のnpx実行時はパッケージのダウンロードが発生し、数秒かかることがあります

• クライアントがシェル環境を継承する場合、環境変数はシェル環境からも取得できます（envブロックは不要）

MCP Inspectorでのデバッグ：

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

変数の設定

1. MCP設定のenvブロック（推奨。プラットフォーム間で最も信頼性が高い）— 上記のenvオブジェクトに変数を記述します

2. .envファイル（ローカル開発）— .env.exampleを.envにコピーして記入し、node --env-file-if-exists=.env dist/index.jsを実行します（Node 22ネイティブ、dotenv不要）

3. シェルのexport — export OPENAI_API_KEY=sk-xxxを実行してから起動

キーがないプロバイダーはlist_providersで利用不可と表示され、呼び出し時に不足している変数が報告されます。

公開（npxが機能する前に）

pnpm publish          # or pnpm release (changeset flow)

環境変数

各プロバイダーのAPI_KEY、BASE_URL、MODELは環境変数で上書きできます（規約: <PROVIDER_PREFIX>_API_KEY / <PROVIDER_PREFIX>_BASE_URL / <PROVIDER_PREFIX>_MODEL）：

? = 任意（組み込みデフォルトあり）; * = 必須。

グローバル設定：

フォールバックチェーン

複数のプロバイダーが利用可能な場合、呼び出しは優先順位チェーンを辿ります：設定されたデフォルト → VISION_MCP_PROVIDER_PRIORITYリスト → 表の順序（利用不可のプロバイダーはスキップされます）。

• 各プロバイダーは、プロバイダーエラー（上流の障害、タイムアウト）発生時にVISION_MCP_MAX_RETRIES回までリトライされます

• プロバイダーがリトライを使い切ると、チェーン内の次の利用可能なプロバイダーが試行され、VISION_MCP_MAX_FALLBACKS回までフォールバックします

• リトライ/フォールバックが発生するのはプロバイダーエラーのみです。設定エラーや画像エラーは即座に失敗します

• 明示的にprovider引数が指定された場合は、そのプロバイダーのみが試行されます（フォールバックなし）

• すべてが失敗した場合、エラーには試行されたすべてのプロバイダーとその最終エラーが列挙されます

argvでも指定可能：--provider-priority=...、--max-retries=N、--max-fallbacks=N（環境変数より優先）。

MCP起動引数（argv）

各プロバイダーのapiKey / baseUrl / modelは起動引数で上書きできます（環境変数より優先度が高い）。形式は--<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

• グローバル: --default-provider <name> / --default-model <name>

• プロバイダーごと: --<provider>-api-key、--<provider>-base-url、--<provider>-model（イコール形式とスペース形式の両方に対応）

• 任意のOpenAI互換サードパーティサービス: --openai-compat-base-url + --openai-compat-api-key + --openai-compat-modelで1行で接続可能。または、任意の組み込みプロバイダーのbase-urlをミラー/プロキシに向けることも可能

優先順位: ツール引数のprovider/model > 起動引数（プロバイダーごと > グローバルデフォルト） > 環境変数 > プロバイダーの組み込みデフォルト。

ツール

imageは以下を受け付けます：ローカルパス / http(s):// URL / data: URI / 生のbase64。自動判別されます。

セキュリティ上の注意: URLダウンロードはSSRF保護されています。すべてのホップ（リダイレクトを含む）が検証され、ループバック、プライベート、リンクローカルアドレスに解決されるURLはブロックされます（エラーにその理由のヒントが含まれます）。

プロバイダー統合（3段階フォールバックチェーン）

プロバイダーの追加: OpenAI 互換エンドポイントの場合、src/core/config.ts の RULES に 1 行追加し、src/index.ts のファクトリテーブルに 1 つのマッピングを追加するだけで、新しいコードは不要です。公式 SDK またはネイティブ fetch の実装は SPEC §1 を参照してください。

開発

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

実呼び出しスモークテスト（API キーが設定されているプロバイダーに対してのみ実行され、それ以外ではスキップされます）:

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

アーキテクチャ

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

完全な仕様: SPEC.md。