luma-mcp
多模型视觉理解 MCP 服务器,为不支持图片理解的 AI 编码模型提供视觉能力:分析截图、报错、UI 与文档,可接入多家主流视觉大模型。Multi-model vision MCP server that adds image understanding to AI coding models without native vision — analyze screenshots, errors, UI and documents via major vision LLM providers.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jochenyang--luma-mcp)HTML
<a href="/listings/jochenyang--luma-mcp"><img src="/api/listings/jochenyang--luma-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
直接通过 `npx` 运行(无需本地安装):
npx -y luma-mcp
或从源码构建:
git clone https://github.com/JochenYang/luma-mcp.git cd luma-mcp npm install npm run build
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 393 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Luma MCP
- 多模型视觉理解 MCP 服务器,为不支持原生视觉能力的 AI 助手提供统一的图片分析能力。
- [English](./docs/README_EN.md) | 中文
- ## 特性
- - **多模型支持**:GLM-4.6V、DeepSeek-OCR、Qwen3-VL-Flash、Doubao-Seed-1.6、Hunyuan-Vision
- - **单工具设计**:统一通过 `image_understand` 完成图片理解,兼容旧客户端
- - **面向复杂截图优化**:大图自动多裁剪、文本密集场景保真处理
- - **统一预处理链路**:本地文件、远程 URL、Data URI 都进入同一套处理流程
- - **适用场景完整**:代码截图、UI 截图、报错截图、文档截图、OCR
- - **标准 MCP 协议**:可接入 Claude Desktop、Cline、Claude Code 等客户端
- - **HTTP / Docker 部署**:局域网内多客户端共享一个实例(v1.7.0+)
- - **内置重试**:降低临时网络或模型请求失败带来的影响
- ## 快速开始
- ### 前置要求
- - Node.js >= 18
- - 任意一个模型提供商的 API Key
- ### 安装
- 直接通过 `npx` 运行(无需本地安装):
- ```bash
- npx -y luma-mcp
- ```
- 或从源码构建:
- ```bash
- git clone https://github.com/JochenYang/luma-mcp.git
- cd luma-mcp
- npm install
- npm run build
- ```
- ## 不使用 MCP?Luma Vision Skill(轻量替代)
- 不想安装 MCP 服务器,或你使用的 AI 客户端(如 Kimi Code)支持 skill 而不支持 MCP?可直接使用仓库内的 `vision-skill/`:
- - **安装**:把 `vision-skill/` 目录复制到你所用 agent 的 skills 目录(如 `~/.agents/skills/vision-skill`)
- - **激活**:发送图片时以 `/skill luma-vision` 开头,skill 会执行 `scripts/vision.js` 直连视觉模型 API 完成分析
- - **配置**:在系统环境变量中设置(与 MCP 版 `custom` provider 共用同一组变量):
- | 变量 | 说明 |
- | ---- | ---- |
- | `CUSTOM_BASE_URL` | OpenAI 兼容 API 地址(默认 `https://api.minimaxi.com/v1`) |
- | `CUSTOM_MODEL_NAME` | 模型名称(默认 `MiniMax-M3`) |
- | `CUSTOM_API_KEY` | API Key |
- **与 MCP 版的差异**:skill 是零依赖轻量脚本,只做"单图直连"——支持本地路径、HTTP(S) URL、Data URI,图片参数留空时自动扫描常见缓存目录找最新图片;但不包含 MCP 版的多裁剪、压缩、重试、SSRF 防护等能力。
- ## 配置
- ### 基础配置(npx 方式)
- 在 MCP 客户端的 `mcpServers` 中注册(Claude Desktop、Cline / VSCode 通用):
- ```json
- {
- "mcpServers": {
- "luma": {
- "command": "npx",
- "args": ["-y", "luma-mcp"],
- "env": {
- "MODEL_PROVIDER": "zhipu",
- "ZHIPU_API_KEY": "your-api-key"
- }
- }
- }
- }
- ```
- 将 `MODEL_PROVIDER` 与对应的 API Key 环境变量替换为实际使用的提供商:
- | `MODEL_PROVIDER` | API Key 环境变量 |
- | ---------------- | ---------------- |
- | `zhipu` | `ZHIPU_API_KEY` |
- | `siliconflow` | `SILICONFLOW_API_KEY` |
- | `qwen` | `DASHSCOPE_API_KEY` |
- | `volcengine` | `VOLCENGINE_API_KEY` |
- | `hunyuan` | `HUNYUAN_API_KEY` |
- | `custom` | `CUSTOM_API_KEY` + `CUSTOM_BASE_URL` + `CUSTOM_MODEL_NAME` |
- 默认模型见[提供商密钥](#提供商密钥)表;如需覆盖模型,可追加 `MODEL_NAME` 环境变量,例如:
- - `MODEL_NAME=doubao-seed-1-6-vision-250815`(Volcengine 视觉深度思考模型)
- - `MODEL_NAME=hy-vision-2.0-instruct`(Hunyuan,腾讯云 TokenHub)
- > [!NOTE]
- > **混元模型已迁移**:腾讯混元平台的旧视觉模型(`hunyuan-t1-vision-20250916`、`Tencent HY Vision 1.5 Instruct` 等)已于 2026-06-22 下线,新模型(HY-Vision 2.0 等)迁移至[腾讯云 TokenHub](https://cloud.tencent.com/product/tokenhub)。luma 的 `hunyuan` provider 默认端点仍指向旧平台;改用 TokenHub 新模型时,建议以 `custom` provider 接入,将 `CUSTOM_BASE_URL` 设为 `https://tokenhub.tencentmaas.com/v1`。
- ### Claude Code 快捷命令
- ```bash
- # Zhipu
- claude mcp add -s user luma-mcp --env MODEL_PROVIDER=zhipu --env ZHIPU_API_KEY=your-api-key -- npx -y luma-mcp
- # SiliconFlow
- claude mcp add -s user luma-mcp --env MODEL_PROVIDER=siliconflow --env SILICONFLOW_API_KEY=your-api-key -- npx -y luma-mcp
- # Qwen
- claude mcp add -s user luma-mcp --env MODEL_PROVIDER=qwen --env DASHSCOPE_API_KEY=your-api-key -- npx -y luma-mcp
- # Volcengine
- claude mcp add -s user luma-mcp --env MODEL_PROVIDER=volcengine --env VOLCENGINE_API_KEY=your-api-key --env MODEL_NAME=doubao-seed-1-6-vision-250815 -- npx -y luma-mcp
- # Hunyuan(新模型在腾讯云 TokenHub,旧混元平台模型已下线)
- claude mcp add -s user luma-mcp --env MODEL_PROVIDER=hunyuan --env HUNYUAN_API_KEY=your-api-key --env MODEL_NAME=hy-vision-2.0-instruct -- npx -y luma-mcp
- ```
- ### 本地开发模式
- 指向本地 `build/index.js`(将 `<项目路径>` 替换为你本机的项目绝对路径):
- ```json
- {
- "mcpServers": {
- "luma": {
- "command": "node",
- "args": ["<项目路径>/build/index.js"],
- "env": {
- "MODEL_PROVIDER": "zhipu",
- "ZHIPU_API_KEY": "your-api-key"
- }
- }
- }
- }
- ```
- 若 MCP 客户端支持设置工作目录,也可直接使用相对路径 `build/index.js` 并把 cwd 指向项目根目录。
- ### HTTP / Docker 部署(局域网共享,v1.7.0+)
- 默认走 stdio(本地进程)。需要局域网内多个客户端共享一个实例时,改用 **Streamable HTTP** 传输:
- ```bash
- # 本地直接运行(HTTP 模式)
- MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_TOKEN=your-token node build/index.js
- ```
- Docker 部署:
- ```bash
- docker build -t luma-mcp .
- docker run -d --name luma-mcp -p 3000:3000 \
- -e MODEL_PROVIDER=zhipu \
- -e ZHIPU_API_KEY=your-api-key \
- -e MCP_HTTP_TOKEN=your-token \
- luma-mcp
- ```
- 客户端配置(Claude Desktop / Cline 等支持 URL 方式的客户端):
- ```json
- {
- "mcpServers": {
- "luma": {
- "type": "http",
- "url": "http://<服务器IP>:3000/mcp",
- "headers": {
- "Authorization": "Bearer your-token"
- }
- }
- }
- }
- ```
- > [!IMPORTANT]
- > **务必设置 `MCP_HTTP_TOKEN`**:HTTP 模式下任何能访问该端口的人都能调用 `image_understand`,消耗你的模型 API 额度。
- >
- > **图片来源限制**:HTTP 模式下 `image_source` 只支持 HTTP(S) URL 与 Data URI,**本地文件路径不可用**(服务端在远端,读不到客户端文件);Data URI 传入的图片上限约 10MB(受请求体 30MB 限制)。
- ### Custom Provider(v1.5.0+)
- 使用任意 OpenAI 兼容端点(OpenAI、OpenRouter、Together AI、Anthropic 代理、本地 vLLM/Ollama 等):
- ```bash
- claude mcp add -s user luma-mcp \
- --env MODEL_PROVIDER=custom \
- --env CUSTOM_API_KEY=sk-your-key \
- --env CUSTOM_BASE_URL=https://your-endpoint.com/v1 \
- --env CUSTOM_MODEL_NAME=your-model \
- -- npx -y luma-mcp
- ```
- 可选配置(都有默认值):
- - `CUSTOM_AUTH_HEADER=bearer` — `bearer` / `x-api-key` / `custom`
- - `CUSTOM_PATH=/chat/completions` — API 路径
- - `CUSTOM_TIMEOUT_MS=60000` — 超时毫秒
- - `CUSTOM_THINKING_MODE=disabled` — `disabled` / `openai` / `qwen_extra_body`
- - `CUSTOM_AUTH_HEADER_VALUE="X-API-Key: {{key}}"` — 自定义 Header 模板(`{{key}}` 会被替换为 API Key)
- ## 使用
- ### `image_understand`
- **单一工具**,参数:
- | 参数 | 必填 | 说明 |
- | ---- | ---- | ---- |
- | `image_source` | 是 | 粘贴路径、本地文件路径、HTTP(S) 图片 URL 或 Data URI |
- | `prompt` | 是 | 用户对图片的原始问题,无需手写长分析模板 |
- | `task_type` | 否 | `auto` \| `general` \| `ocr` \| `ui` \| `debug` \| `describe` |
- `task_type` 行为:
- - 省略或 `auto`(默认):与旧版一致,按 prompt 启发式路由
- - `ocr`:文字提取,默认单图高保真(关闭 multi-crop)
- - `ui` / `debug`:界面结构 / 报错截图,倾向文本保真
- - `describe`:简短描述
- 示例:
- ```typescript
- image_understand({
- image_source: "./screenshot.png",
- prompt: "分析这个页面的布局和主要组件结构",
- task_type: "ui",
- });
- image_understand({
- image_source: "./code-error.png",
- prompt: "这段代码为什么报错?请给出修复建议",
- // task_type 可省略,行为与旧版兼容
- });
- image_understand({
- image_source: "https://example.com/ui.png",
- prompt: "找出这个界面的可用性问题",
- });
- ```
- ### 使用建议
- - 非视觉模型需要明确提示调用 MCP 工具
- - 代码截图、OCR、长图、表格这类文本密集图片会自动启用更保真的处理方式
- - 大图会按配置自动生成原图加裁剪图,提高细节理解能力
- - 需要排查耗时/裁剪数时设 `INCLUDE_META=true` 或 `LUMA_DEBUG=1`,结果末尾会附 `luma_meta`
- ## 环境变量
- ### 通用配置
- | 变量名 | 默认值 | 说明 |
- | ------ | ------ | ---- |
- | `MODEL_PROVIDER` | `zhipu` | 模型提供商:`zhipu`、`siliconflow`、`qwen`、`volcengine`、`hunyuan`、`custom` |
- | `MODEL_NAME` | 自动选择 | 模型名称覆盖 |
- | `MAX_TOKENS` | `8192` | 最大生成 token 数(部分模型有硬上限,见下方说明) |
- | `TEMPERATURE` | `0.7` | 采样温度 |
- | `TOP_P` | `0.95` | 核采样阈值 |
- | `ENABLE_THINKING` | `true` | 思考模式,设为 `false` 关闭 |
- | `MULTI_CROP` | `true` | 大图多裁剪,设为 `false` 关闭 |
- | `MULTI_CROP_MAX_TILES` | `5` | 多裁剪最大图块数(含原图,1–16) |
- | `BASE_VISION_PROMPT` | 内置默认值 | 自定义基础视觉提示词(设为空字符串可关闭) |
- | `INCLUDE_META` | `false` | 为 `true` 时在工具结果末尾附加预处理/API 耗时等 meta |
- | `LUMA_DEBUG` | 关闭 | `1`/`true` 时等同开启 `INCLUDE_META` |
- | `MCP_TRANSPORT` | `stdio` | 传输方式:`stdio`(默认)或 `http`(Streamable HTTP) |
- | `MCP_HTTP_HOST` | `0.0.0.0` | HTTP 模式监听地址(Docker 内需为 `0.0.0.0`) |
- | `MCP_HTTP_PORT` | `3000` | HTTP 模式监听端口 |
- | `MCP_HTTP_TOKEN` | 空(不鉴权) | HTTP 模式 Bearer token;**局域网共享务必设置** |
- > [!IMPORTANT]
- > **关于 Token 限制的特别说明:**
- >
- > 1. **SiliconFlow (DeepSeek-OCR)**: 该模型的总上下文长度(输入+输出)仅为 **8192**。为了确保图片能正常输入,Luma 已在客户端内部将 `MAX_TOKENS` 硬性限制在 **4096** 以内。即使你在环境变量中设置了更高的值,也会被截断。
- > 2. **通用建议**: 视觉理解任务通常不需要极长的输出。对于大多数模型,建议将 `MAX_TOKENS` 保持在 `4096` 或 `8192`。设置过高(如 `16384`)在处理大图时,可能因总长度超过模型上限而导致 `400` 错误。
- ### 提供商密钥
- | 提供商 | 必填环境变量 | 默认模型 |
- | ------ | ------------ | -------- |
- | Zhipu | `ZHIPU_API_KEY` | `glm-4.6v` |
- | SiliconFlow | `SILICONFLOW_API_KEY` | `deepseek-ai/DeepSeek-OCR` |
- | Qwen | `DASHSCOPE_API_KEY` | `qwen3-vl-flash` |
- | Volcengine | `VOLCENGINE_API_KEY` | `doubao-seed-1-6-flash-250828` |
- | Hunyuan | `HUNYUAN_API_KEY` | `hunyuan-t1-vision-20250916` |
- ## 图片限制与处理
- - 支持格式:JPG、PNG、WebP、GIF
- - 最大输入大小:10MB(本地文件、远程 URL、Data URI 一致)
- - 超过 2MB 的图片会自动压缩
- - 最大分辨率:1600 万像素(超出将报错)
- - 远程 URL 会先拉取到统一预处理链路再发送给模型,并带 SSRF 防护(拒绝内网/私网地址、禁用重定向)
- - 长边 ≥ 1800px 或 ≥ 350 万像素的大图,自动生成原图 + 有序裁剪图(受 `MULTI_CROP` / `MULTI_CROP_MAX_TILES` 控制)
- ## 本地测试
- ```bash
- # 单元测试(不调用真实 API)
- npm run test:unit
- # MCP stdio 端到端测试(真实调用 image_understand)
- npm run test:mcp
- # MCP HTTP 传输测试(无需 API key)
- npm run test:http
- # 基础测试
- npm run test:local ./test.png
- # 带问题测试
- npm run test:local ./code-error.png "这段代码为什么报错?"
- # 远程图片测试
- npm run test:local https://example.com/image.jpg
- # 检查源码和测试脚本类型
- npm run typecheck
- ```
- ## 模型选择建议
- - OCR、文字识别:DeepSeek-OCR
- - 快速低成本通用分析:Qwen3-VL-Flash
- - 高性价比通用分析:Doubao-Seed-1.6
- - 深度图片理解:GLM-4.6V
- - 复杂图文推理、多语言:Hunyuan-Vision(新模型为混元 HY-Vision,见腾讯云 TokenHub)
- ## 项目结构
- ```text
- luma-mcp/
- ├── src/
- │ ├── index.ts # MCP 服务器入口,注册 image_understand
- │ ├── http-server.ts # Streamable HTTP 传输层(鉴权/会话/CORS)
- │ ├── config.ts # 环境变量加载与校验
- │ ├── constants.ts # 默认视觉提示词等常量
- │ ├── task-types.ts # 可选 task_type 路由
- │ ├── vision-client.ts # 视觉模型客户端接口
- │ ├── openai-compatible-client.ts # OpenAI 兼容请求基类
- │ ├── zhipu-client.ts # GLM-4.6V 客户端
- │ ├── siliconflow-client.ts # DeepSeek-OCR 客户端
- │ ├── qwen-client.ts # Qwen3-VL 客户端
- │ ├── volcengine-client.ts # Doubao-Seed-1.6 客户端
- │ ├── hunyuan-client.ts # Hunyuan-Vision 客户端
- │ ├── custom-client.ts # 任意 OpenAI 兼容端点
- │ ├── image-processor.ts # 图片预处理、压缩、多裁剪
- │ └── utils/
- │ ├── helpers.ts # 重试、响应格式化、错误脱敏
- │ └── logger.ts # 日志
- ├── test/
- │ ├── test-local.ts # 本地单图/多图测试
- │ ├── test-qwen.ts # Qwen 客户端测试
- │ ├── test-deepseek-raw.ts # DeepSeek-OCR 原始调用测试
- │ ├── test-data-uri.ts # Data URI 处理测试
- │ ├── test-custom.ts # CustomClient 单元测试
- │ ├── test-task-types.ts # task_type 路由测试
- │ ├── test-mcp-stdio.ts # MCP stdio 端到端测试
- │ ├── test-mcp-http.ts # MCP HTTP 传输测试(无需 API key)
- │ └── image-processor-regression.ts # 图片处理回归测试
- ├── Dockerfile # HTTP 模式容器化部署
- ├── vision-skill/ # 轻量识图 skill(无 MCP 用户的替代方案)
- │ ├── SKILL.md # skill 定义:/skill luma-vision 激活
- │ └── scripts/vision.js # 零依赖识图脚本,直连视觉模型 API
- ├── docs/
- │ └── README_EN.md
- ├── build/ # 编译产物
- ├── package.json
- └── tsconfig.json
- ```
- ## 开发
- ```bash
- npm run watch
- npm run build
- npm run typecheck
- ```
- ## 相关链接
- - [智谱开放平台](https://open.bigmodel.cn/)
- - [硅基流动平台](https://cloud.siliconflow.cn/)
- - [阿里云百炼](https://bailian.console.aliyun.com/)
- - [火山方舟](https://console.volcengine.com/ark)
- - [腾讯混元](https://cloud.tencent.com/product/hunyuan)
- - [MCP 协议](https://modelcontextprotocol.io/)
- ## 更新历史
- [CHANGELOG.md](./CHANGELOG.md)
- ## 许可证
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.