Vision MCP Server

基于 Model Context Protocol (MCP) 的图像识别服务器，使用 Node.js + TypeScript 实现，通过 OpenAI 兼容 API 调用任意视觉模型（默认示例：GLM-4V / Qwen-VL 等）。

这是同仓库 Python 版 MCP Vision Server 的 Node.js 移植版本，功能与 Python 版完全保持一致（已按需省略 Web 配置工具），并完整兼容 .env 配置。

✨ 特性

• 🖼 图像分析 - 支持本地文件路径与 Base64 编码输入
• 💬 两轮对话 - 基于图像的连续问答，自动维护会话状态
• 🔌 OpenAI 兼容 - 任意 OpenAI 兼容视觉模型（GLM-4V、Qwen-VL、GPT-4o 等）
• 💾 会话持久化 - 对话历史可持久化到 ~/.mcp-vision/history.json
• 🧰 多客户端支持 - 已验证兼容 OpenCode、Pi、Trae / Claude Desktop / Claude Code

📦 环境要求

• Node.js >= 18
• npm / pnpm / yarn 任一
• 一个支持视觉的 OpenAI 兼容 API（智谱 GLM-4V、通义千问 Qwen-VL、OpenAI GPT-4o 等）

🚀 快速开始

1. 安装依赖并构建

cd vision-mcp
npm install
npm run build

构建产物输出到 dist/ 目录。

2. 配置环境变量

cp .env.example .env

编辑 .env，填入您的 API 配置：

# 必填
VISION_API_KEY=your-api-key-here
VISION_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
VISION_MODEL=glm-4v

3. 直接运行

npm start
# 或
node dist/index.js

成功启动后会输出：

2026-... - vision-mcp - INFO - 启动 Vision MCP Server 服务器
2026-... - vision-mcp - INFO - 模型: glm-4v
2026-... - vision-mcp - INFO - MCP 服务器已启动，等待 stdio 连接...

⚠️ 安全提示：本仓库的 .env.example 可能在您本地被填入了真实密钥，切勿提交到 Git 仓库。.gitignore 已默认忽略 .env，请确认无误后安全保存。

⚙️ 环境变量

| 变量名 | 说明 | 默认值 | |---|---|---| | VISION_API_KEY | API 密钥（必填） | - | | VISION_BASE_URL | OpenAI 兼容 API 地址（必填） | - | | VISION_MODEL | 视觉模型名 | glm-4v | | VISION_MAX_IMAGE_SIZE | 最大图像字节数 | 20971520 (20MB) | | VISION_TIMEOUT | 请求超时（毫秒） | 120000 | | VISION_TEMPERATURE | 温度参数（0.0-2.0） | 0.7 | | VISION_MAX_TOKENS | 最大输出 tokens | 4096 | | VISION_LOG_LEVEL | 日志级别（DEBUG/INFO/WARNING/ERROR） | INFO | | VISION_MAX_HISTORY | 对话历史最大条数 | 50 | | VISION_ENABLE_PERSISTENCE | 是否启用历史持久化 | true | | VISION_HISTORY_PATH | 历史文件路径 | ~/.mcp-vision/history.json |

🛠 提供的 MCP 工具

1. analyze_image — 图像分析

{
  "image": "C:/path/to/image.png",
  "prompt": "详细描述这张图片"
}

支持 image/png、image/jpeg、image/gif、image/webp、image/bmp、image/tiff 等格式。

2. chat_vision — 两轮对话

{
  "image": "C:/path/to/image.png",
  "question": "这张图显示什么数据？",
  "session_id": null,            // 首次不传
  "is_new_conversation": false   // 传 session_id 继续
}

返回的 session_id 可用于追问第二轮（最多 2 轮，超过会自动结束会话）。

3. get_status — 服务器状态

无参数，返回当前配置、模型、活跃会话数等信息。

🔧 客户端接入配置

下面给出主流 MCP 客户端的接入方法。统一使用 stdio 模式（直接通过命令行进程通信）启动服务器：

{
  "command": "node",
  "args": ["/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
  "env": {
    "VISION_API_KEY": "your-api-key-here",
    "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
    "VISION_MODEL": "glm-4v"
  }
}

👉 路径请改为您本机 vision-mcp 目录的绝对路径。 已在 package.json 中注册 bin: vision-mcp，全局安装后也可直接用 "command": "vision-mcp"。

1) OpenCode

OpenCode 使用 opencode.json 作为全局 MCP 配置（也可放在项目根的 opencode.json）。

配置文件位置：

• 全局：~/.config/opencode/opencode.json
• 项目：<project>/opencode.json

配置内容：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["node", "/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
      "environment": {
        "VISION_API_KEY": "your-api-key-here",
        "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
        "VISION_MODEL": "glm-4v"
      },
      "enabled": true
    }
  }
}

也可直接使用 .env 文件，将环境变量交由本服务器内部 dotenv 加载，此时 environment 字段可省略：

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["node", "/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

启动 OpenCode 后，可在提示词中通过 可以使用 vision 工具分析... 调用，或在 TUI 中输入 /mcp 查看工具列表。

2) Pi

Pi（Pi Coding Agent）的 MCP 配置位于 ~/.pi/config.json，支持 stdio 传输。

配置内容：

{
  "mcpServers": {
    "vision": {
      "type": "stdio",
      "command": "node",
      "args": ["/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
      "env": {
        "VISION_API_KEY": "your-api-key-here",
        "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
        "VISION_MODEL": "glm-4v"
      }
    }
  }
}

如果 Pi 安装时已通过 npm 全局安装本包（npm i -g ./vision-mcp），可简化为：

{
  "mcpServers": {
    "vision": {
      "type": "stdio",
      "command": "vision-mcp"
    }
  }
}

3) Trae IDE / Trae CLI

Trae IDE 兼容 Claude Code 的 MCP 配置文件，编辑 ~/.claude.json（或 IDE 内置 MCP → 编辑配置）。

配置内容：

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
      "env": {
        "VISION_API_KEY": "your-api-key-here",
        "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
        "VISION_MODEL": "glm-4v"
      }
    }
  }
}

在 Trae 中使用

1. 打开 Trae IDE，进入 设置 → MCP 或 Agent 配置。

2. 点击 编辑 mcp_servers.json，粘贴上述配置（替换路径与 API Key）。

3. 保存后回到 IDE，在 MCP 列表确认 vision 已变为 Connected。

4. 在对话中输入：

   请使用 vision 工具分析这张图：/abs/path/to/image.png，并描述其中的关键信息。

如果 Trae 全局安装了 vision-mcp，也可省略 args：

{
  "mcpServers": {
    "vision": { "command": "vision-mcp" }
  }
}

4) 其他兼容客户端（Claude Desktop / Claude Code / Cursor）

配置格式同上 mcpServers，例如 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/workspaces/aiProjects/mcp-vision-server/vision-mcp/dist/index.js"],
      "env": {
        "VISION_API_KEY": "your-api-key-here",
        "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
        "VISION_MODEL": "glm-4v"
      }
    }
  }
}

🧪 本地调试

在终端中可直接通过 stdio 与服务器交互：

cd vision-mcp
cp .env.example .env   # 填好密钥
node dist/index.js

服务器启动后会等待 stdio JSON-RPC 请求，输入 Ctrl+C 退出。

触发一次工具调用

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_status","arguments":{}}}' \
  | node dist/index.js

📁 目录结构

vision-mcp/
├── src/
│   ├── config.ts          # 配置管理（对应 config.py）
│   ├── utils.ts           # 工具函数
│   ├── imageProcessor.ts  # 图像处理（路径 / Base64）
│   ├── visionClient.ts    # OpenAI 兼容 API 客户端
│   ├── chatManager.ts     # 对话管理器（两轮对话 + 持久化）
│   ├── logger.ts          # stderr 日志
│   ├── server.ts          # MCP 服务器注册
│   └── index.ts           # 入口
├── dist/                  # tsc 编译产物
├── .env.example           # 环境变量模板
├── package.json
├── tsconfig.json
└── README.md

📜 许可证

MIT License