Click on "Deploy 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 Vision MCP Can you describe what's in this image?"
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.
为纯文本大模型（DeepSeek 等）补齐视觉理解能力的 MCP Server
基于 luma-mcp (v1.7.0) 迭代增强
本项目基于 JochenYang/luma-mcp 的 v1.7.0 版本进行二次开发和迭代增强，保留了原项目的核心图片预处理能力（压缩、自适应裁剪、SSRF 防护、LRU 缓存等），并在此基础上新增了三大核心特性。
衷心感谢原作者 @JochenYang 的开源贡献。 原项目 luma-mcp 是一个非常优秀的视觉理解 MCP Server，本项目在其基础上进行了以下增强：
维度 | 原项目 luma-mcp v1.7.0 | 本项目 luma-vision-mcp v2.0 |
Provider 模式 | 单 Provider，主挂了报错 | 多 Provider Fallback 链（sequential/race） |
视觉描述策略 | 固定 Prompt | Focus Hint 上下文感知（10 维度匹配） |
工具数量 | 1 个（image_understand） | 3 个（+ image_ocr + image_compare） |
图片预处理 | ✅ 保留 | ✅ 完整保留（压缩/裁剪/SSRF/缓存） |
HTTP/Docker | ✅ 保留 | 规划中（后续版本） |
配置方式 | 纯环境变量 | 环境变量（兼容）+ Fallback 链扩展 |
Related MCP server: vision-mcp
不再依赖单一视觉模型。配置主备 Provider 链，主 Provider 失败自动切换备用：
主：智谱 GLM-4.6V（免费）→ 备1：硅基 DeepSeek-OCR → 备2：阿里 Qwen-VL两种降级策略：
sequential（默认）：按优先级依次尝试，失败换下一个
race：同时向多个 Provider 发请求，谁快用谁
不再泛泛地"描述这张图"。系统自动分析用户 prompt，提取关注维度，让视觉模型只描述当前需要的细节：
用户："这个按钮什么颜色？"
→ Focus Hint = "Focus on color: exact names, hex values, contrast..."
→ 视觉模型只描述颜色，省 token、更精准支持 10 个维度自动匹配：颜色、文字、布局、结构、错误、样式、位置、图标、数据、对比。
工具 | 用途 | 亮点 |
| 通用图片理解 | Focus Hint + task_type 自动路由 |
| 专用 OCR 文字提取 | 语言提示 + 格式输出 + 单图高保真 |
| 图片对比 | 结构化差异报告（类型/严重级别） |
推荐 智谱 AI（永久免费视觉模型）：
访问 bigmodel.cn 注册账号
进入控制台 → API Keys → 创建新 Key
复制你的 API Key
git clone https://github.com/你的用户名/luma-vision-mcp.git
cd luma-vision-mcp
npm install
npm run build编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）：
{
"mcpServers": {
"luma-vision": {
"command": "node",
"args": ["/absolute/path/to/luma-vision-mcp/dist/index.js"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "你的智谱APIKey"
}
}
}
}编辑 ~/.cursor/mcp.json：
{
"mcpServers": {
"luma-vision": {
"command": "node",
"args": ["/absolute/path/to/luma-vision-mcp/dist/index.js"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "你的智谱APIKey"
}
}
}
}claude mcp add -s user luma-vision \
--env MODEL_PROVIDER=zhipu \
--env ZHIPU_API_KEY=你的智谱APIKey \
-- node /absolute/path/to/luma-vision-mcp/dist/index.js同样格式，将 command 和 args 和 env 填入对应 MCP 配置位置即可。
重启 MCP 客户端，在对话中上传一张图片或提供图片路径，然后提问：
请帮我看一下这个截图的内容 /Users/demo/screenshot.png模型会自动调用 image_understand 工具完成视觉理解。
只需 2 个环境变量：
MODEL_PROVIDER=zhipu
ZHIPU_API_KEY=你的Key{
"mcpServers": {
"luma-vision": {
"command": "node",
"args": ["/path/to/dist/index.js"],
"env": {
"MODEL_PROVIDER": "zhipu",
"ZHIPU_API_KEY": "智谱Key",
"FALLBACK_CHAIN": "siliconflow,qwen",
"FALLBACK_STRATEGY": "sequential",
"SILICONFLOW_API_KEY": "硅基流动Key",
"DASHSCOPE_API_KEY": "阿里云Key"
}
}
}
}效果：智谱 → 硅基 → 阿里，依次降级，任一成功即返回。
MODEL_PROVIDER=zhipu
ZHIPU_API_KEY=智谱Key
FALLBACK_CHAIN=siliconflow
FALLBACK_STRATEGY=race
SILICONFLOW_API_KEY=硅基Key效果：智谱和硅基同时发起请求，谁先返回用谁的结果——更快更可靠。
变量 | 默认值 | 说明 |
|
| 主 Provider |
| (空) | 备用 Provider 链，逗号分隔 |
|
|
|
|
| Focus Hint 上下文感知开关 |
|
| 大图自动裁剪 |
|
| 最大裁剪数 |
|
| 视觉模型深度思考 |
|
| 最大输出 token |
|
| 温度 |
|
| Top-P |
|
| 结果末尾附加调用元信息 |
| (空) | 设为 |
Provider | 默认模型 | 环境变量 | 免费情况 |
| glm-4.6v |
| 永久免费 |
| DeepSeek-OCR |
| 有免费额度 |
| qwen3-vl-flash |
| 新用户免费 |
| doubao-seed |
| 有限免费 |
| hunyuan-t1-vision |
| 有限免费 |
| 用户自定义 |
| 取决于端点 |
MODEL_PROVIDER=custom
CUSTOM_API_KEY=sk-your-key
CUSTOM_BASE_URL=https://your-endpoint.com/v1
CUSTOM_MODEL_NAME=your-model-name用户："看一下这个界面截图的布局"
模型 → 调用 image_understand(image_source="截图路径", prompt="看一下这个界面截图的布局")
→ Focus Hint 匹配到 "layout" 维度
→ 视觉模型聚焦描述布局信息
→ 返回结构化的界面分析可选 task_type：
auto（默认）：自动推断
general：通用分析
ocr：文字提取
ui：界面结构
debug：报错诊断
describe：简短描述
用户："提取这张图片里的所有文字"
模型 → 调用 image_ocr(image_source="文档路径", language_hint="zh", output_format="markdown")
→ 单图高保真模式（不裁剪）
→ 返回格式化的文字内容用户："对比设计稿和实现，找出差异"
模型 → 调用 image_compare(image_source_a="设计稿", image_source_b="实现截图")
→ 两张图同时传入视觉模型
→ 返回差异表格（类型/严重级别/描述）本项目的 OCR 工具专注于图片中的文字。如果是 PDF 文档解析，建议配合本地 MinerU skill 使用：
图片截图 / 代码截图 / 表单照片 → 使用 image_ocr
PDF 文档 / 扫描书籍 / 论文 → 使用 MinerU skill
两者互为补充，覆盖全部文档处理场景。
用户上传图片
↓
image_understand / image_ocr / image_compare
↓
Focus Hint 引擎（10维度上下文感知匹配）
↓
图片预处理（验证 → 压缩 → 自适应裁剪 → LRU缓存）
↓
Fallback Manager
├─ Primary: 智谱 GLM-4.6V（免费）
├─ Fallback: 硅基 DeepSeek-OCR
└─ Fallback: 阿里 Qwen-VL
↓
视觉模型返回文字描述 → 纯文本模型获得"视觉"SSRF 防护：DNS 解析 + 私有 IP 检测 + 禁止重定向
路径遍历防护：symlink 解析 + 白名单目录
像素限制：最大 1600 万像素，防止 OOM
错误脱敏：Bearer token / API Key 自动遮蔽
# 安装依赖
npm install
# 编译
npm run build
# 类型检查
npm run typecheck
# 开发模式（监听变更）
npm run devsrc/
├── config.ts # 多 Provider 配置 + Fallback 链解析
├── constants.ts # 提示词常量（含 OCR/对比专用 Prompt）
├── focus-hint.ts # Focus Hint 引擎（10 维度匹配）
├── image-processor.ts # 图片预处理（压缩/裁剪/SSRF/缓存）
├── index.ts # 主入口（3 个 MCP 工具注册）
├── task-types.ts # 任务类型路由
├── vision-client.ts # 客户端接口定义
├── providers/
│ ├── fallback-manager.ts # Fallback 降级管理器
│ ├── openai-compatible.ts # OpenAI 兼容客户端基类
│ └── index.ts # Provider 工厂
└── utils/
├── helpers.ts # 重试/响应构建/错误脱敏
└── logger.ts # stderr 日志器MIT — 见 LICENSE
本项目基于 luma-mcp（MIT License）迭代开发，感谢原作者的贡献。
完整的行业调研报告和方案对比见项目根目录的调研文档，涵盖了 20+ 个同类开源项目的详细分析。
对比两张图片的差异。适合场景：设计稿vs实现、修改前后对比、找不同。 返回结构化的差异报告，包含差异类型、严重级别和描述。
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | 可选的对比重点描述，如'只关注颜色差异'或'检查布局是否一致' | |
| image_source_a | Yes | 图片A（参考图/基准图）：路径/URL/Data URI | |
| image_source_b | Yes | 图片B（目标图/对比图）：路径/URL/Data URI |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (structured difference report with type, severity, and description), adding value beyond the schema. However, it does not mention whether the tool is read-only, potential limitations, or edge cases. Since no annotations are provided, the description carries the full burden but only partially fulfills it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action, followed by use cases and output summary. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, appropriate scenarios, and output structure, which is adequate for basic understanding. However, it lacks details about edge cases, limitation, or how to interpret the report fields beyond their names. With no annotations or output schema, more context could be expected for a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the description does not need to add parameter semantics. The description does not elaborate on parameters beyond what the schema already provides, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '对比两张图片的差异' (compare differences between two images). The specific scenarios (design vs implementation, before/after, spot-the-difference) help distinguish it from sibling tools like image_understand and image_ocr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases ('设计稿vs实现、修改前后对比、找不同') that indicate when to use this tool. It does not explicitly mention exclusions or alternatives, but the sibling tool names give implicit context for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
专用OCR文字提取工具。从图片中高精度提取所有文字内容，保留格式和阅读顺序。 适合场景：文档截图、代码截图、表格、表单、扫描件。 如果是PDF文档，建议使用本地MinerU skill处理。
| Name | Required | Description | Default |
|---|---|---|---|
| image_source | Yes | 要提取文字的图片（路径/URL/Data URI） | |
| language_hint | No | 语言提示，帮助OCR引擎优化识别 | |
| output_format | No | 输出格式：纯文本、Markdown（保留表格结构）或JSON（结构化） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool preserves formatting and reading order and implicitly states image-only input by redirecting PDFs to another tool. However, it does not describe output structure or edge cases, which is acceptable for a simple OCR tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences: purpose, suitable scenarios, and PDF alternative. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple and has no output schema, but the output_format parameter covers return types. The description provides essential context (scenarios, PDF limitation) and is sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions; the only extra context is that formatting/reading order is preserved, which aligns with the output_format parameter but is not essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it is a specialized OCR tool that extracts all text from images with high precision while preserving formatting and reading order. This distinguishes it from sibling tools (image_understand, image_compare) which are not focused on text extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists suitable scenarios (document screenshots, code screenshots, tables, forms, scanned documents) and provides a clear alternative for PDFs (use MinerU skill). This gives the agent specific when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通用图像理解工具。当用户提到看图/截图/界面/报错/布局，或对话中出现图片附件并询问图片相关问题时调用。 图片来源：粘贴图路径、本地路径、HTTP(S) URL、Data URI。 直接传入用户原始问题即可，服务端会自动注入 Focus Hint 和基础视觉协议。 task_type（可选）：auto|general|ocr|ui|debug|describe。省略或auto时自动推断。
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | 用户关于图片的原始问题或指令 | |
| task_type | No | 可选任务类型。省略或auto=自动推断。ocr=文字提取；ui=界面；debug=报错；describe=简述 | |
| image_source | Yes | 要分析的图片：本地路径、HTTP(S) URL 或 data:image/...;base64,...（PNG/JPG/WebP/GIF，最大约10MB） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It reveals a notable behavioral detail: '服务端会自动注入 Focus Hint 和基础视觉协议', explaining automatic server-side processing. However, it omits potential side effects, authentication needs, rate limits, or response format, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph that front-loads the core purpose, then efficiently covers triggers, image sources, usage, and optional task_type. Each sentence contributes useful information without redundancy, though it is slightly dense and could be broken into clearer sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides solid context for when to use the tool, image formats, and task_type semantics, which helps an agent select and invoke it. However, since there is no output schema, the description should explain what the tool returns (e.g., text, analysis), but it does not, leaving a significant gap in expected response understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to repeat parameter details. The description adds minimal extra meaning by clarifying that 'prompt' should be the user's original question and by summarizing task_type's auto-inference behavior, but this largely mirrors the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a '通用图像理解工具' (general image understanding tool) and lists trigger scenarios like viewing images, screenshots, interfaces, errors, and layouts. It effectively communicates the resource and action, but does not explicitly distinguish itself from sibling tools (image_ocr, image_compare), relying on the word '通用' to imply a broader scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use instructions: '当用户提到看图/截图/界面/报错/布局，或对话中出现图片附件并询问图片相关问题时调用'—covering common triggers and image attachment scenarios. It also advises to '直接传入用户原始问题即可', giving practical usage direction, though it does not mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0image_compareimage_ocrimage_understandScored across 3 tools
Each tool has a clearly distinct purpose: general understanding, high-precision OCR, and image comparison. The optional OCR task type in image_understand could cause minor overlap, but the descriptions clearly position image_ocr as the specialized tool.
All tool names share the 'image_' prefix and use snake_case, which is consistent. However, 'image_ocr' uses an acronym while the others use verbs, creating a minor stylistic inconsistency.
With only 3 tools, the server is well-scoped and each tool covers a fundamental vision task. This is appropriate for a focused utility without unnecessary bloat.
The toolset covers the core image understanding workflows: general QA, text extraction, and diff comparison. Minor gaps like explicit image metadata extraction or more granular analysis options exist, but the primary use cases are well supported.
MCP server for Qwen Image 3 AI image generation
MCP server for building and testing AI agents with multi-model experimentation and insights.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
An MCP server that integrates with Discord to provide AI-powered features.