understand-image-mcp

通过用户配置的视觉大模型对图片进行识别分析的 MCP 服务器。支持 OpenAI 协议的各种视觉模型 API。

工作原理

用户 → Claude Code → understand-image-mcp → 视觉大模型 API → 返回分析结果

快速开始

1. 配置 API

方式一：命令行配置（推荐）

npx understand-image-mcp config --set baseUrl=https://api-inference.modelscope.cn/v1 --set apiKey=你的APIKey --set model=Qwen/Qwen3-VL-235B-A22B-Instruct

方式二：手动创建配置文件

mkdir -p ~/.config/understand-image
cat > ~/.config/understand-image/config.json << 'EOF'
{
  "baseUrl": "https://api-inference.modelscope.cn/v1",
  "apiKey": "你的APIKey",
  "model": "Qwen/Qwen3-VL-235B-A22B-Instruct"
}
EOF

配置保存在 ~/.config/understand-image/config.json，全局生效。

查看当前配置：

npx understand-image-mcp config

2. 连接 Claude Code

前提：需要先全局安装

npm install -g understand-image-mcp

安装一次即可，MCP 服务器会随 Claude Code 自动启动。

方式一：使用 npx（未克隆仓库）

项目级配置 — 在项目目录创建 .mcp.json：

{
  "mcpServers": {
    "understand_image": {
      "command": "npx",
      "args": ["understand-image-mcp"]
    }
  }
}

全局配置 — 在 ~/.claude.json 的 mcpServers 节点中添加：

{
  "mcpServers": {
    "understand_image": {
      "command": "npx",
      "args": ["understand-image-mcp"]
    }
  }
}

方式二：使用源码（克隆仓库后）

git clone https://github.com/kakaxi3019/understand-image-mcp.git
cd understand-image-mcp
npm install
npm link  # 创建全局链接

项目级配置 — 在项目目录创建 .mcp.json：

{
  "mcpServers": {
    "understand_image": {
      "command": "node",
      "args": ["/path/to/understand-image-mcp/src/server.js"]
    }
  }
}

全局配置 — 在 ~/.claude.json 的 mcpServers 节点中添加：

{
  "mcpServers": {
    "understand_image": {
      "command": "node",
      "args": ["/path/to/understand-image-mcp/src/server.js"]
    }
  }
}

配置好后，Claude Code 会自动启动 MCP，无需手动运行。

3. 使用

让 Claude Code 分析图片：

用户：帮我看看 images/screenshot.png 有什么问题
Claude Code：（调用 MCP 分析图片）这张截图显示...

支持的图片

• 本地路径：/path/to/image.jpg
• 网络 URL：https://example.com/image.jpg
• 格式：JPEG, PNG, WebP, GIF, BMP

支持的视觉模型

| 服务商 | Base URL | 说明 | |--------|----------|------| | ModelScope | https://api-inference.modelscope.cn/v1 | 阿里云，每日免费额度，推荐 | | Ollama | http://localhost:11434/v1 | 本地运行，免费，需安装 Ollama | | LM Studio | http://localhost:1234/v1 | 本地运行，免费，需安装 LM Studio | | OpenAI | https://api.openai.com/v1 | 需要 API Key | | Azure | https://xxx.openai.azure.com | 企业级，需要 API Key |

ModelScope 快速获取 API Key

1. 注册 https://modelscope.cn
2. 获取 API Key：https://modelscope.cn/user-center/m API-Key
3. 推荐模型：Qwen/Qwen3-VL-235B-A22B-Instruct

命令

npx understand-image-mcp config              # 查看当前配置
npx understand-image-mcp config --set key=value  # 设置配置项
npx understand-image-mcp                      # 手动启动 MCP（调试用）

注意：通过 Claude Code 使用时，MCP 会根据 .mcp.json 配置自动启动，通常无需手动运行。

手动管理 MCP 服务器

正常使用时 Claude Code 会自动管理，无需手动操作。如需手动控制：

启动 MCP：

npx understand-image-mcp

服务器会一直运行，按 Ctrl+C 停止。

后台运行：

npx understand-image-mcp &   # 后台运行
kill %1                       # 关闭后台进程

查看配置：

npx understand-image-mcp config

开发者命令（源码方式）

如果克隆了仓库，可以手动运行：

node src/cli.mjs config              # 查看配置
node src/cli.mjs config --set key=value  # 设置配置
node src/cli.mjs                      # 运行 MCP（仅调试用）