llm-vision

给没有视觉能力的大语言模型（如 DeepSeek）提供一个「借眼」工具：识别本地图片，返回文字描述，模型根据返回文字信息进行推理。

目录

1. 这个项目能做什么

2. 项目组成：MCP + Skill

3. 适用范围

4. 项目结构

5. 安装位置

6. 快速开始

7. 手动安装

8. 使用方法

9. 配置选项

10. 安全说明

11. 更新记录

12. 许可证

Related MCP server: image-mcp

1. 这个项目能做什么

给纯文本模型补上"眼睛"，让它能处理图片：

• 描述画面：图片里有什么、什么场景

• 看图认人：这张图里的人是谁

• 提取文字：图片里的文字内容（OCR）

• 定向问答：只回答你问的细节，如"他穿的什么颜色"

纯文本模型收到图片只会显示 "Unsupported Image"。本工具把图片编码后发给通义千问 VL 视觉模型，拿回文字描述，模型就能基于文字回答你的问题。

2. 项目组成：MCP + Skill

本项目由两部分组成，能力互补：

一句话：MCP = 眼睛（能不能看），Skill = 纪律（怎么看得好）。 缺 MCP 看不了图，缺 Skill 会"可能看一眼就乱说"。

2.1 Skill 规范了什么

Skill（image-recognition）给模型立了三条行为规则：

外加一条升级规则（用于"这人/这物具体是谁"这类需要准确结论的场景）：

具体对比：

3. 适用范围

本项目是标准 MCP 服务器，任何支持 MCP 协议的客户端都能接入：Claude Code、Codex、Cursor、Gemini CLI、Cline 等。

Skill 走 Agent Skills 开放标准（agentskills.io），Claude Code / Codex / Cursor / Gemini CLI 均原生支持，复制 skills/image-recognition/ 到各自 skills 目录即可：

• Claude Code → .claude/skills/

• Codex → .agents/skills/ 或 ~/.agents/skills/

• Gemini CLI → .agents/skills/ 或 .gemini/skills/

• Cursor → .cursor/skills/（也兼容直接读 .claude/skills/）

不支持的客户端可参考第 2 节的行为规则，用对应的项目指令文件实现。

4. 项目结构

llm-vision/
├── server.mjs                    # 核心：MCP 服务器（describe_image 工具）
├── skills/
│   └── image-recognition/        # 可选 Skill（Agent Skills 开放标准）
│       └── SKILL.md
├── package.json                  # 依赖（@modelcontextprotocol/sdk、zod）
├── package-lock.json             # 依赖锁定（勿手改）
├── install.sh                    # 一键部署
├── .env.example                  # API Key 配置模板
├── .gitignore                    # 忽略 node_modules / .env
└── README.md                     # 本文件

5. 安装位置

5.1 MCP → 注册到 ~/.claude.json

MCP 通过注册挂到客户端，配置写入 ~/.claude.json（Windows：C:\Users\<用户名>\.claude.json）：

"mcpServers": {
  "llm-vision": {
    "type": "stdio",
    "command": "node",
    "args": ["<项目绝对路径>/server.mjs"],
    "env": { "DASHSCOPE_API_KEY": "sk-xxx" }
  }
}

上面这段 JSON 就是 ~/.claude.json 里 mcpServers 字段的内容。claude mcp add 命令的本质就是帮你在该文件里写入这段（二选一：用命令，或手改文件）。

命令怎么读（user 是作用域，llm-vision 才是服务名）：

claude mcp add -s user llm-vision -e DASHSCOPE_API_KEY=xxx -- node server.mjs
              └┬──┘└──┬───┘└──┬─────┘
           作用域选项 值     服务名    启动命令

scope 取值：

• -s local（默认，不带 -s 等同）→ 项目级，只在本项目可用

• -s user（install.sh 用这个）→ 用户级全局，写 ~/.claude.json，所有项目可用

• -s project → 项目级（通过项目内配置）

5.2 Skill → 复制到 skills 目录

Skill 要复制到 Claude Code 的 skills 目录才生效：

~/.claude/skills/
└── image-recognition/
    └── SKILL.md

推荐直接用全局（~/.claude/skills/，install.sh 选 y 时自动装到这儿）：一份搞定，所有项目都能用，省心。

只有少数情况才装到项目级（<项目>/.claude/skills/）：比如某个项目想用定制版 Skill，其他项目不用。日常都选全局。

仓库里 skills/image-recognition/ 是源文件，装到全局/项目都是复制一份过去，仓库那份留着以便以后更新重装。

6. 快速开始

需要 Node.js ≥ 18，以及阿里云百炼 API Key（申请地址）。

git clone <仓库地址>
cd llm-vision

# Claude Code 用户：装依赖 + 配 Key + 注册 MCP + 询问是否装 Skill
bash install.sh

# 其他客户端（Cursor/Codex/Cline）：只装依赖 + 配 Key
bash install.sh --no-claude

install.sh 会询问是否安装 Skill：选 y 安装，选 n 或回车跳过。也可用 --no-skill 直接跳过。

7. 手动安装

前提：以下命令在项目目录内执行。先拿到源码并进入目录：

git clone <仓库地址>
cd llm-vision

7.1 Claude Code 用户

npm install
cp .env.example .env        # 编辑 .env 填入 DASHSCOPE_API_KEY
claude mcp add -s user llm-vision -e DASHSCOPE_API_KEY=<你的Key> -- node <项目绝对路径>/server.mjs
claude mcp list             # 应显示 llm-vision Connected

装 Skill（可选）：

cp -r skills/image-recognition ~/.claude/skills/

为什么仓库里已有 skills/image-recognition/ 还要复制？ 仓库里的是源文件（跟随版本分发）。但 Claude Code 的 Skill 只从 ~/.claude/skills/ 加载，不会自动读你仓库里的目录。cp 就是把源文件"安装"到生效位置，install.sh 选 y 时自动做这一步。

7.2 其他客户端（Cursor / Codex / Cline 等）

装依赖 + 配 Key，然后在各自的 MCP 配置文件里加下面这段（文件位置见下表）：

{
  "mcpServers": {
    "llm-vision": {
      "type": "stdio",
      "command": "node",
      "args": ["<项目绝对路径>/server.mjs"],
      "env": { "DASHSCOPE_API_KEY": "<你的Key>" }
    }
  }
}

大部分客户端用上面同一个 JSON 结构（type/command/args/env）。Codex 例外：它是 TOML 格式，且顶层键是下划线 mcp_servers（不是 mcpServers）：

# ~/.codex/config.toml 或 .codex/config.toml
[mcp_servers.llm-vision]
command = "node"
args = ["<项目绝对路径>/server.mjs"]
enabled = true

[mcp_servers.llm-vision.env]
DASHSCOPE_API_KEY = "<你的Key>"

也可以用命令：codex mcp add llm-vision -- node <项目绝对路径>/server.mjs（配环境变量加 --env DASHSCOPE_API_KEY=xxx）。

8. 使用方法

配置完成后重启 Claude Code，直接说：

• 「看 /path/to/photo.jpg 这个人是谁」

• 「帮我描述这张图：/path/to/photo.jpg」

• 「提取这张图里的文字」

其他 MCP 客户端可按标准协议直接调用 describe_image(image_path, prompt?)。

9. 配置选项

省钱建议：日常识图用 qwen-vl-plus（免费额度常用款）或 qwen3-vl-flash（第二代性价比款）；复杂图文、OCR、图表分析用 qwen-vl-max 或 qwen3-vl-plus（更强）。

10. 安全说明

本项目不含任何真实 API Key，Key 通过环境变量注入（模板见 .env.example）。.env 和 node_modules 已被 .gitignore 忽略，不会上传。部署时不要把你的 Key 写进代码或提交到仓库。

11. 更新记录

12. 许可证

MIT