Vision MCP Server

一个 Model Context Protocol (MCP) 服务器，为连接到非多模态模型的智能体提供视觉理解能力（DeepSeek、旧版 GPT-4、本地小模型等）：智能体将图像交给 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 的端点

• 三种图像输入：本地路径 / http(s) URL / base64（data URI 或原始 base64），自动识别

• 三级回退链：官方 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 版本（发布到 npm 后可用）：

{
  "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 运行会下载包，可能需要几秒钟

• 环境变量也可以来自 shell 环境（如果客户端继承了它，则无需 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. Shell 导出——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；或者将任何内置提供商的 base-url 指向镜像/代理

优先级：工具参数 provider/model > 启动参数（按提供商 > 全局默认）> 环境变量 > 提供商内置默认值。

工具

image 接受：本地路径 / http(s):// URL / data: URI / 原始 base64，自动识别。

安全说明： URL 下载受 SSRF 保护——每一跳（包括重定向）都会经过验证，解析到回环地址、私有地址或链路本地地址的 URL 会被阻止（错误信息中的提示会说明原因）。

提供商集成（三级回退链）

添加提供商：对于 OpenAI 兼容端点，在 src/core/config.ts 的 RULES 中添加一行，并在 src/index.ts 的工厂表中添加一个映射——零新增代码。官方 SDK 或原生 fetch 实现：参见 SPEC §1。

开发

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

真实调用冒烟测试（仅对已配置密钥的提供商运行；否则跳过）：

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。