Luma MCP

多模型视觉理解 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 等客户端
• 内置重试：降低临时网络或模型请求失败带来的影响

快速开始

前置要求

• 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

配置

Claude Desktop 示例

{
  "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

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 模板

快捷配置命令

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-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"
      }
    }
  }
}

Cline / VSCode

在项目根目录或 .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：用户对图片的原始问题

示例：

image_understand({
  image_source: "./screenshot.png",
  prompt: "分析这个页面的布局和主要组件结构",
});

image_understand({
  image_source: "./code-error.png",
  prompt: "这段代码为什么报错？请给出修复建议",
});

image_understand({
  image_source: "https://example.com/ui.png",
  prompt: "找出这个界面的可用性问题",
});

使用建议

• 非视觉模型需要明确提示调用 MCP 工具
• 代码截图、OCR、长图、表格这类文本密集图片会自动启用更保真的处理方式
• 大图会按配置自动生成原图加裁剪图，提高细节理解能力

环境变量

通用配置

... View full README on GitHub