The Luma MCP server provides a unified, multi-model image understanding tool (image_understand) for AI assistants, enabling comprehensive visual analysis through a single interface.
What you can do:
Analyze images from multiple sources: Local file paths, remote HTTP(S) URLs, Data URIs, or pasted attachments (PNG, JPG, JPEG, WebP, GIF, up to 10MB)
Understand UI/frontend screenshots: Analyze page layouts, component structures, and interface elements
Perform OCR / text extraction: Extract text from documents, forms, and tables with high fidelity, optimized for text-dense images
Debug code & error screenshots: Identify errors in code screenshots, understand log outputs, and get fix suggestions
Describe general images: Get short or detailed descriptions of any image content
Use task-specific routing: Optionally specify a task_type (auto, general, ocr, ui, debug, describe) to optimize analysis for your use case
Automatic image preprocessing: Large images (>2MB) are auto-compressed and/or split into multiple crops for better detail understanding
Multiple vision model backends: Backed by GLM-4.6V, DeepSeek-OCR, Qwen3-VL-Flash, Doubao-Seed-1.6, and Hunyuan-Vision-1.5, with support for custom OpenAI-compatible endpoints
Integrate with any MCP-compatible client: Works with Claude Desktop, Cline, Claude Code, and other MCP-compatible tools
Configurable settings: API keys per provider, MAX_TOKENS, custom base vision prompts, and debug options
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Luma MCP 分析这个页面的布局和主要组件结构"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
多模型视觉理解 MCP 服务器，为不支持原生视觉能力的 AI 助手提供统一的图片分析能力。
English | 中文
多模型支持：GLM-4.6V、DeepSeek-OCR、Qwen3-VL-Flash、Doubao-Seed-1.6、Hunyuan-Vision-1.5
单工具设计：统一通过 image_understand 完成图片理解
面向复杂截图优化：支持大图多裁剪、文本密集场景保真处理
统一预处理链路：本地文件、远程 URL、Data URI 都进入同一套处理流程
适用场景完整：代码截图、UI 截图、报错截图、文档截图、OCR
标准 MCP 协议：可接入 Claude Desktop、Cline、Claude Code 等客户端
内置重试：降低临时网络或模型请求失败带来的影响
Related MCP server: MCP Vision Server
Node.js >= 18
任意一个模型提供商的 API Key
git clone https://github.com/JochenYang/luma-mcp.git
cd luma-mcp
npm install
npm run build也可以在 MCP 配置中直接使用：
npx -y luma-mcp{
"mcpServers": {
"luma": {
"command": "npx",
"args": ["-y", "luma-mcp"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "your-api-key"
}
}
}
}把 MODEL_PROVIDER 和对应密钥替换为你实际使用的提供商：
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（任意 OpenAI 兼容端点）
可选模型覆盖：
MODEL_NAME=doubao-seed-1-6-flash-250828
MODEL_NAME=hunyuan-t1-vision-20250916
MODEL_NAME=HY-vision-1.5-instruct
使用任意 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 模板
# 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-flash-250828 -- npx -y luma-mcp
# Hunyuan
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=hunyuan --env HUNYUAN_API_KEY=your-api-key --env MODEL_NAME=hunyuan-t1-vision-20250916 -- npx -y luma-mcp{
"mcpServers": {
"luma": {
"command": "node",
"args": ["D:\\codes\\luma-mcp\\build\\index.js"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "your-api-key"
}
}
}
}在项目根目录或 .vscode/ 下创建 mcp.json：
{
"mcpServers": {
"luma": {
"command": "npx",
"args": ["-y", "luma-mcp"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "your-api-key"
}
}
}
}image_understand仍为单一工具（兼容旧客户端）。参数：
image_source：本地路径、HTTP(S) 图片 URL、Data URI
prompt：用户对图片的原始问题
task_type（可选）：auto | general | ocr | ui | debug | describe
省略或 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
变量名 | 默认值 | 说明 |
|
| 模型提供商： |
| 自动选择 | 模型名称 |
| 内置默认值 | 自定义基础视觉提示词 |
|
| 最大生成 token 数（部分模型有硬上限，详见下方说明） |
|
| 为 |
| 关闭 |
|
关于 Token 限制的特别说明：
SiliconFlow (DeepSeek-OCR): 该模型的总上下文长度（输入+输出）仅为 8192。为了确保图片能正常输入，Luma 已在客户端内部将 MAX_TOKENS 硬性限制在 4096 以内。即使你在环境变量中设置了更高的值，也会被截断。
通用建议: 视觉理解任务通常不需要极长的输出。对于大多数模型，建议将 MAX_TOKENS 保持在 4096 或 8192。设置过高（如 16384）在处理大图时，可能因总长度超过模型上限而导致 400 错误。
提供商 | 必填环境变量 | 默认模型 |
Zhipu |
|
|
SiliconFlow |
|
|
Qwen |
|
|
Volcengine |
|
|
Hunyuan |
|
|
# 单元测试（不调用真实 API）
npm run test:unit
# 基础测试
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支持格式：JPG、PNG、WebP、GIF
最大输入大小：10MB
超过 2MB 的图片会自动压缩
远程 URL 会先拉取到统一预处理链路，再发送给模型
luma-mcp/
├── src/
│ ├── index.ts # MCP 服务器入口
│ ├── config.ts # 配置管理
│ ├── task-types.ts # 可选 task_type 路由
│ ├── vision-client.ts # 视觉模型客户端接口
│ ├── openai-compatible-client.ts # OpenAI 兼容基类
│ ├── zhipu-client.ts # GLM 客户端
│ ├── siliconflow-client.ts # DeepSeek-OCR 客户端
│ ├── qwen-client.ts # Qwen VL 客户端
│ ├── volcengine-client.ts # Doubao 客户端
│ ├── hunyuan-client.ts # Hunyuan 客户端
│ ├── custom-client.ts # 任意 OpenAI 兼容端点
│ ├── image-processor.ts # 图片预处理与裁剪
│ └── utils/
│ ├── helpers.ts
│ └── logger.ts
├── test/
│ ├── test-local.ts
│ ├── test-qwen.ts
│ ├── test-deepseek-raw.ts
│ └── test-data-uri.ts
├── docs/
│ └── README_EN.md
├── build/
├── package.json
└── tsconfig.jsonOCR、文字识别：DeepSeek-OCR
快速低成本通用分析：Qwen3-VL-Flash
高性价比通用分析：Doubao-Seed-1.6
深度图片理解：GLM-4.6V
复杂图文推理、多语言：Hunyuan-Vision-1.5
npm run watch
npm run build
npm run typecheckMIT
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Multimodal video analysis MCP — transcription, vision, and OCR for any video URL.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/JochenYang/luma-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server