Luma MCP

多模型视觉理解 MCP 服务器，为不支持原生视觉能力的 AI 助手提供统一的图片分析能力。

English | 中文

特性

多模型支持：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 运行（无需本地安装）：

npx -y luma-mcp

或从源码构建：

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 通用）：

{
  "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。luma 的 hunyuan provider 默认端点仍指向旧平台；改用 TokenHub 新模型时，建议以 custom provider 接入，将 CUSTOM_BASE_URL 设为 https://tokenhub.tencentmaas.com/v1。

Claude Code 快捷命令

# 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（将 <项目路径> 替换为你本机的项目绝对路径）：

{
  "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 传输：

# 本地直接运行（HTTP 模式）
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_TOKEN=your-token node build/index.js

Docker 部署：

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 方式的客户端）：

{
  "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 等）：

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：简短描述

示例：

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 限制的特别说明：

SiliconFlow (DeepSeek-OCR): 该模型的总上下文长度（输入+输出）仅为 8192。为了确保图片能正常输入，Luma 已在客户端内部将 MAX_TOKENS 硬性限制在 4096 以内。即使你在环境变量中设置了更高的值，也会被截断。
通用建议: 视觉理解任务通常不需要极长的输出。对于大多数模型，建议将 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 控制）

本地测试

# 单元测试（不调用真实 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）

项目结构

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

开发

npm run watch
npm run build
npm run typecheck

更新历史

CHANGELOG.md

许可证

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
docs		docs
src		src
test		test
vision-skill		vision-skill
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.check.json		tsconfig.check.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Luma MCP

特性

快速开始

前置要求

安装

不使用 MCP？Luma Vision Skill（轻量替代）

配置

基础配置（npx 方式）

Claude Code 快捷命令

本地开发模式

HTTP / Docker 部署（局域网共享，v1.7.0+）

Custom Provider（v1.5.0+）

使用

`image_understand`

使用建议

环境变量

通用配置

提供商密钥

图片限制与处理

本地测试

模型选择建议

项目结构

开发

相关链接

更新历史

许可证

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Luma MCP

特性

快速开始

前置要求

安装

不使用 MCP？Luma Vision Skill（轻量替代）

配置

基础配置（npx 方式）

Claude Code 快捷命令

本地开发模式

HTTP / Docker 部署（局域网共享，v1.7.0+）

Custom Provider（v1.5.0+）

使用

image_understand

使用建议

环境变量

通用配置

提供商密钥

图片限制与处理

本地测试

模型选择建议

项目结构

开发

相关链接

更新历史

许可证

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`image_understand`