Luma MCP

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

English | 中文

特性

• 多模型支持: 支持五个视觉模型
  • GLM-4.6V（智谱清言）- 付费，中文理解优秀
  • DeepSeek-OCR（硅基流动）- 免费使用，OCR 能力强
  • Qwen3-VL-Flash（阿里云通义千问）- 付费，速度快成本低，支持思考模式
  • Doubao-Seed-1.6（火山方舟）- 付费，性价比高，支持多种版本
  • Hunyuan-Vision-1.5（腾讯混元）- 付费，图文推理强，多语言表现优秀
• 简单设计: 单一 image_understand 工具处理所有图片分析任务
• 智能理解: 自动识别代码、UI、错误等不同场景
• 全面支持: 代码截图、界面设计、错误诊断、OCR 文字识别
• 标准 MCP 协议: 无缝集成 Claude Desktop、Cline 等 MCP 客户端
• URL 支持: 支持本地文件和远程图片 URL
• 重试机制: 内置指数退避重试，提高可靠性

快速开始

前置要求

• Node.js >= 18.0.0
• 选择一种模型：
  • 方案 A: 智谱 AI API Key (获取地址) - 中文理解优秀
  • 方案 B: 硅基流动 API Key (获取地址) - 免费使用，OCR 能力强
  • 方案 C: 阿里云百炼 API Key (获取地址) - 速度快成本低，支持思考模式
  • 方案 D: 火山方舟 API Key (获取地址) - 性价比高，支持多种版本
• 方案 E: 腾讯混元 API Key (获取地址) - 图文推理强，多语言表现优秀

安装

方式 1: 本地开发（推荐用于测试）

git clone https://github.com/JochenYang/luma-mcp.git
cd luma-mcp
npm install
npm run build

方式 2: 使用 npx（需要先发布到 npm）

npx luma-mcp

配置

Claude Desktop

方案 A: 使用智谱 GLM-4.6V:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "ZHIPU_API_KEY": "your-zhipu-api-key"
      }
    }
  }
}

方案 B: 使用硅基流动 DeepSeek-OCR（免费）:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "siliconflow",
        "SILICONFLOW_API_KEY": "your-siliconflow-api-key"
      }
    }
  }
}

方案 C: 使用阿里云通义千问 Qwen3-VL-Flash:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "qwen",
        "DASHSCOPE_API_KEY": "your-dashscope-api-key"
      }
    }
  }
}

方案 D: 使用火山方舟 Doubao-Seed-1.6:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "volcengine",
        "VOLCENGINE_API_KEY": "your-volcengine-api-key",
        "MODEL_NAME": "doubao-seed-1-6-flash-250828"
      }
    }
  }
}

方案 E: 使用腾讯混元 Hunyuan-Vision-1.5:

MODEL_NAME 可选：hunyuan-t1-vision-20250916（默认）或 HY-vision-1.5-instruct

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "hunyuan",
        "HUNYUAN_API_KEY": "your-hunyuan-api-key",
        "MODEL_NAME": "hunyuan-t1-vision-20250916"
      }
    }
  }
}

本地开发（智谱）:

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["D:\\codes\\luma-mcp\\build\\index.js"],
      "env": {
        "ZHIPU_API_KEY": "your-zhipu-api-key"
      }
    }
  }
}

本地开发（硅基流动）:

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["D:\\codes\\luma-mcp\\build\\index.js"],
      "env": {
        "MODEL_PROVIDER": "siliconflow",
        "SILICONFLOW_API_KEY": "your-siliconflow-api-key"
      }
    }
  }
}

本地开发（腾讯混元）:

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["D:\\codes\\luma-mcp\\build\\index.js"],
      "env": {
        "MODEL_PROVIDER": "hunyuan",
        "HUNYUAN_API_KEY": "your-hunyuan-api-key",
        "MODEL_NAME": "hunyuan-t1-vision-20250916"
      }
    }
  }
}

配置完成后重启 Claude Desktop。

Cline (VSCode)

在项目根目录或 .vscode/ 目录下创建 mcp.json

方案 A: 使用智谱 GLM-4.6V:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "ZHIPU_API_KEY": "your-zhipu-api-key"
      }
    }
  }
}

方案 B: 使用硅基流动 DeepSeek-OCR（免费）:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "siliconflow",
        "SILICONFLOW_API_KEY": "your-siliconflow-api-key"
      }
    }
  }
}

方案 C: 使用阿里云通义千问 Qwen3-VL-Flash:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "qwen",
        "DASHSCOPE_API_KEY": "your-dashscope-api-key"
      }
    }
  }
}

方案 D: 使用火山方舟 Doubao-Seed-1.6:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "volcengine",
        "VOLCENGINE_API_KEY": "your-volcengine-api-key",
        "MODEL_NAME": "doubao-seed-1-6-flash-250828"
      }
    }
  }
}

方案 E: 使用腾讯混元 Hunyuan-Vision-1.5:

MODEL_NAME 可选：hunyuan-t1-vision-20250916（默认）或 HY-vision-1.5-instruct

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "hunyuan",
        "HUNYUAN_API_KEY": "your-hunyuan-api-key",
        "MODEL_NAME": "hunyuan-t1-vision-20250916"
      }
    }
  }
}

Claude Code (命令行)

使用智谱 GLM-4.6V:

claude mcp add -s user luma-mcp --env ZHIPU_API_KEY=your-api-key -- npx -y luma-mcp

使用硅基流动 DeepSeek-OCR（免费）:

claude mcp add -s user luma-mcp --env MODEL_PROVIDER=siliconflow --env SILICONFLOW_API_KEY=your-api-key -- npx -y luma-mcp

使用阿里云通义千问 Qwen3-VL-Flash:

claude mcp add -s user luma-mcp --env MODEL_PROVIDER=qwen --env DASHSCOPE_API_KEY=your-api-key -- npx -y luma-mcp

使用火山方舟 Doubao-Seed-1.6:

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-Vision-1.5:

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

其他工具

更多 MCP 客户端配置方法请参考智谱官方文档

使用方法

重要提示

MCP 工具调用机制:

• MCP 工具需要 AI 模型主动调用才会执行
• 如果使用的 AI 模型本身支持视觉（如 Claude 4.5 Sonnet），它会优先使用自己的视觉能力
• Luma MCP 主要服务于不支持视觉的模型（如 GPT-4、Claude Opus 等文本模型）

如何确保工具被调用:

1. 使用完整工具名：使用 mcp__luma-mcp__image_understand 工具分析这张图片
2. 使用简化名称：用 image_understand 工具查看 ./screenshot.png
3. 提供图片路径：请用图片分析工具查看 ./screenshot.png 中的代码错误
4. 明确提及服务器：通过 luma-mcp 服务器分析这张图片

注意: 直接在聊天框粘贴图片，非视觉模型不会自动调用 Luma，需要明确指示。

在 Claude code 中使用

配置完成后，在 Claude 对话中可以这样使用：

推荐用法（明确指示）:

用户: 使用 Luma 分析 ./code-error.png，这段代码为什么报错？
Claude: [调用 Luma 分析图片，返回详细分析]

或提供图片路径:

用户: 请分析 https://example.com/screenshot.jpg 中的界面问题
Claude: [自动调用 image_understand 工具]

本地测试

不需要 MCP 客户端即可测试：

测试智谱 GLM-4.6V:

# 设置 API Key
export ZHIPU_API_KEY="your-api-key"  # macOS/Linux
$env:ZHIPU_API_KEY="your-api-key"    # Windows PowerShell

# 测试本地图片
npm run test:local ./test.png

测试硅基流动 DeepSeek-OCR:

# 设置 API Key 和提供商
export MODEL_PROVIDER=siliconflow
export SILICONFLOW_API_KEY="your-api-key"  # macOS/Linux

$env:MODEL_PROVIDER="siliconflow"
$env:SILICONFLOW_API_KEY="your-api-key"    # Windows PowerShell

# 测试本地图片
npm run test:local ./test.png

测试阿里云通义千问 Qwen3-VL-Flash:

# 设置 API Key 和提供商
export MODEL_PROVIDER=qwen
export DASHSCOPE_API_KEY="your-api-key"  # macOS/Linux

$env:MODEL_PROVIDER="qwen"
$env:DASHSCOPE_API_KEY="your-api-key"    # Windows PowerShell

# 测试本地图片
npm run test:local ./test.png

测试腾讯混元 Hunyuan-Vision-1.5:

# 设置 API Key 和提供商
export MODEL_PROVIDER=hunyuan
export HUNYUAN_API_KEY="your-api-key"  # macOS/Linux

$env:MODEL_PROVIDER="hunyuan"
$env:HUNYUAN_API_KEY="your-api-key"    # Windows PowerShell

# 测试本地图片
npm run test:local ./test.png

其他测试命令:

# 测试并提问
npm run test:local ./code-error.png "这段代码有什么问题？"

# 测试远程URL
npm run test:local https://example.com/image.jpg

工具说明

image_understand

分析图片内容的通用工具。

参数:

• image_source (必需): 图片来源，支持三种格式
  • 本地文件: 绝对路径或相对路径（例：./image.png, C:\Users\...\image.jpg）
  • 远程 URL: https:// 开头的 URL（例：https://example.com/pic.jpg）
  • Data URI: Base64 编码的图片数据（例：data:image/png;base64,iVBORw0KGg...）
  • 支持格式: JPG, PNG, WebP, GIF
• prompt (必需): 分析指令或问题

示例:

// 通用分析
image_understand({
  image_source: "./screenshot.png",
  prompt: "请详细分析这张图片的内容",
});

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

// UI 分析
image_understand({
  image_source: "https://example.com/ui.png",
  prompt: "分析这个界面的布局和可用性问题",
});

// Data URI （当客户端支持时）
image_understand({
  image_source: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  prompt: "识别图片中的所有文字",
});

环境变量

通用配置

| 变量名 | 必需 | 默认值 | 说明 | | ---------------------- | ---- | ------- | ------------------------------------------------------------------- | | MODEL_PROVIDER | 否 | zhipu | 模型提供商：zhipu、siliconflow、qwen、volcengine、hunyuan | | MODEL_NAME | 否 | 见下文 | 模型名称（自动根据提供商选择） | | MAX_TOKENS | 否 | 16384 | 最大生成 tokens | | TEMPERATURE | 否 | 0.7 | 温度参数 (0-1) | | TOP_P | 否 | 0.7 | Top-p 参数 (0-1) | | ENABLE_THINKING | 否 | true | 是否启用思考模式（GLM-4.6V、Qwen3-VL-Flash、Doubao-Seed-1.6） | | MULTI_CROP | 否 | true | 是否启用多裁剪分析（大图文字场景） | | MULTI_CROP_MAX_TILES | 否 | 5 | 多裁剪最大分片数（含原图） |

智谱 GLM-4.6V 专用

| 变量名 | 必需 | 默认值 | 说明 | | --------------- | ---------------- | ------ | ------------------- | | ZHIPU_API_KEY | 是（使用智谱时） | - | 智谱 AI 的 API 密钥 |

默认模型：glm-4.6v

硅基流动 DeepSeek-OCR 专用

| 变量名 | 必需 | 默认值 | 说明 | | --------------------- | -------------------- | ------ | ------------------- | | SILICONFLOW_API_KEY | 是（使用硅基流动时） | - | 硅基流动的 API 密钥 |

默认模型：deepseek-ai/DeepSeek-OCR

阿里云通义千问 Qwen3-VL-Flash 专用

| 变量名 | 必需 | 默认值 | 说明 | | ------------------- | ---------------- | ------ | --------------------- | | DASHSCOPE_API_KEY | 是（使用千问时） | - | 阿里云百炼的 API 密钥 |

默认模型：qwen3-vl-flash

腾讯混元 Hunyuan-Vision-1.5 专用

| 变量名 | 必需 | 默认值 | 说明 | | ----------------- | ---------------- | ------ | ----------------- | | HUNYUAN_API_KEY | 是（使用混元时） | - | 腾讯混元 API 密钥 |

默认模型：hunyuan-t1-vision-20250916

可选模型：HY-vision-1.5-instruct

思考模式说明:

• 默认开启，提高图片分析的准确性和详细程度
• 如需关闭（提高速度、降低成本），请在配置文件中设置：

  {
    "mcpServers": {
      "luma": {
        "command": "npx",
        "args": ["-y", "luma-mcp"],
        "env": {
          "ZHIPU_API_KEY": "your-api-key",
          "ENABLE_THINKING": "false"
        }
      }
    }
  }

• 关闭后可节省 20-30% tokens 消耗，响应速度提升约 30%

开发

# 开发模式（监听文件变化）
npm run watch

# 构建
npm run build

# 本地测试
npm run test:local <图片路径> [问题]

项目结构

luma-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── config.ts             # 配置管理（支持多模型）
│   ├── vision-client.ts      # 视觉模型客户端接口
│   ├── zhipu-client.ts       # GLM-4.6V API 客户端
│   ├── siliconflow-client.ts # DeepSeek-OCR API 客户端
│   ├── qwen-client.ts        # Qwen3-VL API 客户端
│   ├── volcengine-client.ts  # Doubao-Seed-1.6 API 客户端
│   ├── hunyuan-client.ts     # Hunyuan-Vision-1.5 API 客户端
│   ├── image-processor.ts    # 图片处理
│   └── utils/
│       ├── logger.ts         # 日志工具
│       └── helpers.ts        # 工具函数
├── test/
│   ├── test-local.ts         # 本地测试脚本
│   ├── test-qwen.ts          # Qwen 测试脚本
│   ├── test-deepseek-raw.ts  # DeepSeek 原始测试脚本
│   └── test-data-uri.ts      # Data URI 测试脚本
├── docs/
│   ├── design.md             # 设计文档
│   ├── installation.md       # 安装指南
│   └── README_EN.md          # 英文文档
├── build/                    # 编译输出
└── package.json

常见问题

如何获取 API Key？

智谱 GLM-4.6V:

1. 访问 智谱开放平台
2. 注册/登录账号
3. 进入控制台创建 API Key
4. 复制 API Key 到配置文件

硅基流动 DeepSeek-OCR（免费）:

1. 访问 硅基流动平台
2. 注册/登录账号
3. 进入 API 管理创建 API Key
4. 复制 API Key 到配置文件

阿里云通义千问 Qwen3-VL-Flash:

1. 访问 阿里云百炼平台
2. 注册/登录账号
3. 进入 API-KEY 管理创建 API Key
4. 复制 API Key 到配置文件

腾讯混元 Hunyuan-Vision-1.5:

1. 访问 腾讯混元控制台
2. 注册/登录账号
3. 进入 API Key 管理创建 API Key
4. 复制 API Key 到配置文件

支持哪些图片格式？

支持 JPG、PNG、WebP、GIF 格式。建议使用 JPG 格式以获得更好的压缩率。

什么是 Data URI？

Data URI 是一种将图片数据嵌入字符串的方式，格式为：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...

使用场景：

• 当 MCP 客户端（如 Claude Desktop）支持时，可以直接传递用户粘贴的图片
• 无需保存为临时文件，更加高效
• 当前支持状态：服务器已支持，等待客户端实现

图片大小限制？

• 最大文件大小: 10MB
• 超过 2MB 的图片会自动压缩
• 推荐分辨率: 800-2048 像素

如何查看日志？

日志文件位置: ~/.luma-mcp/luma-mcp-YYYY-MM-DD.log

API 调用失败怎么办？

1. 检查 API Key 是否正确
2. 确认账户余额充足（智谱/阿里云）
3. 检查网络连接
4. 查看日志文件了解详细错误信息

成本如何？

硅基流动 DeepSeek-OCR: 完全免费，无需付费！

智谱 GLM-4.6V: 定价请参考智谱官方定价。

阿里云通义千问 Qwen3-VL-Flash: 定价请参考阿里云百炼定价。

典型场景估算（已启用思考模式）：

• 简单图片理解: 500-1000 tokens
• 代码截图分析: 1500-2500 tokens
• 详细 UI 分析: 2000-3000 tokens

关闭思考模式可节省约 20-30% tokens。如需关闭，请设置 ENABLE_THINKING=false。

如何选择模型？

| 特性 | GLM-4.6V（智谱） | DeepSeek-OCR（硅基流动） | Qwen3-VL-Flash（阿里云） | Doubao-Seed-1.6（火山方舟） | Hunyuan-Vision-1.5（腾讯混元） | | ------------- | ---------------- | ------------------------ | ------------------------ | --------------------------- | ------------------------------ | | 费用 | 收费 | 完全免费 | 收费 | 收费 | 收费 | | 中文理解 | 优秀 | 良好 | 优秀 | 优秀 | 优秀 | | OCR 能力 | 良好 | 优秀 | 优秀 | 良好 | 优秀 | | 思考模式 | 支持 | 不支持 | 支持 | 支持 | 默认思考版模型 | | 速度/成本 | 中等 | 免费 | 快速/低成本 | 高性价比 | 中等 | | 适用场景 | 通用图片分析 | OCR、文字识别 | 快速分析、3D 定位 | 高性价比通用分析 | 复杂图文推理、多语言理解 |

推荐:

• 需要 OCR 或文字识别：选择 DeepSeek-OCR（免费）
• 需要快速低成本分析：选择 Qwen3-VL-Flash
• 需要高性价比通用分析：选择 Doubao-Seed-1.6
• 需要深度图片理解：选择 GLM-4.6V
• 需要复杂图文推理或多语言理解：选择 Hunyuan-Vision-1.5

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

相关链接

• 智谱 AI 开放平台
• GLM-4.6V 文档
• 硅基流动平台
• DeepSeek-OCR 文档
• 阿里云百炼平台
• Qwen3-VL 文档
• 腾讯混元平台
• MCP 协议文档

更新日志

更多更新历史请查看 CHANGELOG.md

作者

Jochen

注意: 请勿在公开仓库中提交包含真实 API Key 的配置文件。