luma

Luma MCP 提供一个统一的图片理解入口 image_understand，用于对上传的图片进行多模型分析与推理。通过该服务器，可以从本地图片、网络图片或 Data URI 进入同一条预处理和推理管道，支持多种视觉任务（如文本识别、对象理解、界面/截图分析等），并通过统一的 MCP 接口将结果返回给客户端。核心工具是 image_understand，输入包括 image_source 和 prompt，系统会根据模型提供商自动选择合适的视觉模型并返回分析结果。若需要进行大图裁剪、文本密集场景保真处理等高级分析，系统会开启相应的多裁剪/增强策略，提升细节理解能力。对于不同场景，建议明确 prompt 指令，避免非视觉模型的混用，并可以通过环境变量指定 MODEL_PROVIDER、MODEL_NAME 等来切换模型和密钥。

Prerequisites:

• Node.js >= 18
• npm (随 Node 安装)

Installation steps:

1. 安装并构建本地运行环境

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

2. 直接通过 MCP 配置运行（npx 模式）

npx -y luma-mcp

3. 本地开发模式（如需本地调试 build 产物）

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "your-api-key"
      }
    }
  }
}

注：如需将此 MCP 服务接入到 Claude Code、Cline 等客户端，请在配置中传递 MODEL_PROVIDER 与相应的 API KEY，并按需设置 MODEL_NAME 等可选参数。

Tips:

• 常见问题：如果出现模型请求失败，请检查网络稳定性以及 API Key 是否正确。系统内置重试逻辑，通常能缓解短时网络波动。
• 环境变量：MODEL_PROVIDER 表示模型提供商，配合对应的 KEY 使用。例如 zhipu 使用 ZHIPU_API_KEY；siliconflow 使用 SILICONFLOW_API_KEY。
• 模型选择：通过 MODEL_NAME 指定不同模型，如 doubao-seed-1-6-flash-250828、hunyuan-t1-vision-20250916 等，需确保对应提供商支持。
• 兼容性：本 MCP 服务器与 MCP 协议客户端兼容，可接入 Claude Desktop、Cline、Claude Code 等客户端。确保客户端使用的协议版本与服务器实现一致。
• 图片和处理限制：支持 JPG/PNG/WebP/GIF，最大输入大小及裁剪策略请参考 README。若遇到大图裁剪参数，请根据 MULTI_CROP/MAX_TILES 调整。

环境变量示例：

• 通用配置: MODEL_PROVIDER=zhipu, MODEL_NAME=hunyuan-t1-vision-20250916 等
• 服务端日志级别、最大 Token 数等可按需要调整。若要禁用思考模式，可将 ENABLE_THINKING 设置为 false。