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 共用同一组变量）：

与 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_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 -

... [View full README on GitHub](https://github.com/JochenYang/luma-mcp#readme)