内容
# ImgLume MCP
[](https://github.com/Hanyuyu/imglume-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org/)
一个开源的本地MCP服务器，连接AI客户端到ImgLume，以获取视觉灵感、提示改进、图像生成和编辑以及视频生成。
工具是灵活的构建块。当灵感有用时，搜索画廊；当需要时，改进一个短想法；或者当用户已经知道自己想要什么时，直接生成。
## 工作原理
```text
MCP主机（Codex、Claude Code、Cursor等）
-> 本地ImgLume MCP服务器（此仓库）
-> ImgLume API
-> 生成的文件保存在您的计算机上
```
该仓库仅包含开源的MCP服务器。ImgLume网站和API后端不包含在此。
画廊提示和模型信息从ImgLume的实时目录中读取。因此，新的画廊条目、模型选项和图像或视频信用成本可以在无需MCP更新的情况下变得可用。只有当工具或API合同更改时，才需要更新MCP。
## 看看它的实际效果
下面每个资产都来自公共MCP工具的一次生产运行。虚构的“LUME NO. 7”产品首先被创建，然后与时尚模型参考相结合，最后从保存的本地活动图像中进行动画处理。
| 创建产品 | 构建模型活动 | 动画活动 |
| --- | --- | --- |
|  |  |  |
[观看4秒生成的视频](assets/lume-model-video.mp4)。
## 难点
这些是普通的`generate_image`和`generate_video`调用，而不是硬编码的工作流。它们展示了同一个工具如何一次处理多个约束。
### 一个参考，四个视觉方向
基础瓶子用于四个并行的图像请求：时尚活动、午夜霓虹灯、月光植物学和极简编辑。瓶子几何形状、紫色到琥珀色的液体、黑色盖子和金色标签在艺术方向变化时仍然可识别。
### 两个参考，一个受控的构图
从左到右：产品参考、模型参考和新的活动。请求保留了模型的身份、绿色裙子、瓶子设计和标签，同时将两个对象移到一个温暖的金色工作室。
### 确切的海报副本
这个9:16的海报需要精确的两行标题：“MIDNIGHT BLOOM”和“LUME NO. 7”，同时保留三行产品标签。
### 图像到视频的连续性
0.05秒、1.30秒、2.60秒和3.85秒的帧显示相同的面部、发型、衣服、手势、瓶子和标签，通过缓慢的相机推入和细微的主体运动。
[观看完整的4秒连续性测试](assets/lume-model-video.mp4)。
## 要求
- Node.js 20或更新版本
- 支持本地`stdio`服务器的MCP客户端
- ImgLume账户和API密钥（仅在生成图像或视频时需要）
画廊搜索、灵感细节、提示改进和模型发现不需要API密钥。
## 快速开始
将ImgLume添加到您的MCP客户端：
```json
{
"mcpServers": {
"imglume": {
"command": "npx",
"args": ["-y", "github:Hanyuyu/imglume-mcp"]
}
}
}
```
重启客户端，然后尝试：
> 浏览流行的ImgLume灵感并给我三个不同的视觉方向。
要启用图像和视频生成：
1. [创建ImgLume API密钥](https://imglume.com/settings/apikeys)。ImgLume将指导已注销的用户首先登录。
2. 将密钥添加到服务器的环境中：
```json
{
"mcpServers": {
"imglume": {
"command": "npx",
"args": ["-y", "github:Hanyuyu/imglume-mcp"],
"env": {
"IMGLUME_API_KEY": "imglume_your_key"
}
}
}
}
```
将密钥保存在您的私有本地MCP配置中。永远不要将其提交到仓库中。
### Codex
```bash
codex mcp add imglume -- npx -y github:Hanyuyu/imglume-mcp
```
在需要生成时，在 `--` 之前添加 `--env IMGLUME_API_KEY=imglume_your_key`。
### Claude Code
```bash
claude mcp add --scope user imglume -- npx -y github:Hanyuyu/imglume-mcp
```
在需要生成时，在 `--` 之前添加 `-e IMGLUME_API_KEY=imglume_your_key`。
### Cursor
使用Cursor的MCP配置保存上面的JSON配置：
- `~/.cursor/mcp.json`适用于所有项目
- `.cursor/mcp.json`适用于一个项目
在保存文件后重启Cursor。
## 试用
使用自然语言请求。主机选择相关的工具。
### 查找灵感
> 在ImgLume中搜索海报灵感并给我五个选项。
使用简短、广泛的搜索术语，如`poster`、`product`、`portrait`、`anime`或`cinematic`。留空搜索以浏览热门内容。
### 改进简要描述
> 将以下内容改进为一个适合生产的图像提示：一个雪山上的咖啡杯，编辑风格。
### 生成图像
> 为虚构的LUME NO. 7香水生成一个垂直的奢侈活动：一个成年东亚时尚模特穿着翡翠色的一肩裙，温暖的演播室灯光和清晰可见的产品标签。
### 编辑图像
> 使用`/absolute/path/to/product.png`和`/absolute/path/to/model.png`作为参考。保留模型的身份、裙子、瓶子形状和标签；将它们放在一起在一个温暖的金色演播室中。
### 动画图像
> 将`/absolute/path/to/campaign.png`变成一个4秒的视频。添加细微的转动、眨眼、头发移动和缓慢的相机推入，同时保持面部、手、瓶子和标签稳定。
预览渲染取决于MCP主机。没有内联媒体支持的主机可能会显示一个URL而不是图像或视频本身。
## 工具
| 工具 | 目的 | API密钥 |
| --- | --- | --- |
| `search_gallery` | 搜索实时画廊的视觉参考和提示示例 | 否 |
| `get_inspiration` | 检索完整的提示、媒体、建议和归属 | 否 |
| `enhance_prompt` | 请求当前主机模型改进一个简短的视觉简报 | 否 |
| `list_models` | 读取当前模型、选项、默认值和实时信用成本 | 否 |
| `generate_image` | 生成或编辑一个图像并保存在本地 | 是 |
| `generate_video` | 生成一个视频并保存在本地 | 是 |
每个工具都可以独立使用。画廊搜索是可选的灵感，而不是生成前的必需步骤。
## 生成输入和输出
- 使用`list_models`时，模型选择、支持的选项或当前成本很重要。避免依赖硬编码的模型列表。
- 图像成本按每次生成报告。视频成本按秒报告，因此将选定的费率乘以请求的持续时间。
- 图像生成和视频生成消耗与API密钥关联的ImgLume账户的积分。
- 参考图像可以是公共的HTTP(S) URL或本地文件路径。
- 本地路径应为绝对路径，以便MCP进程解析预期的文件。
- 支持JPG、PNG和WebP参考图像。
- 每个参考图像最多10 MB，最多五个参考图像每个请求。
- MCP验证实时模型、质量和长宽比选项，然后再上传本地参考图像。如果上传或生成提交失败，则会删除部分上传内容。
- 视频时长可在4到15秒之间。可用的质量和长宽比值来自实时模型目录。
- 默认情况下，生成的图像保存在`~/Pictures/imglume`中。
设置`IMGLUME_OUTPUT_DIR`以使用其他保存位置。
## 配置
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `IMGLUME_API_KEY` | 用于生成的ImgLume API密钥 | 无 |
| `IMGLUME_API_URL` | 高级API源覆盖 | `https://imglume.com` |
| `IMGLUME_OUTPUT_DIR` | 生成的文件保存位置 | `~/Pictures/imglume` |
| `IMGLUME_POLL_INTERVAL_MS` | 生成状态轮询间隔 | `2000`（2秒） |
| `IMGLUME_IMAGE_TIMEOUT_MS` | 图像等待超时 | `300000`（5分钟） |
| `IMGLUME_VIDEO_TIMEOUT_MS` | 视频等待超时 | `900000`（15分钟） |
大多数用户应保持`IMGLUME_API_URL`未设置。它仅适用于ImgLume维护人员和受信任的兼容API环境；它不提供用于本地开发的私有ImgLume后端。
配置的API源接收API密钥、提示和上传的参考图像。仅将`IMGLUME_API_URL`指向您信任的端点。
## 隐私和安全
- `search_gallery`、`get_inspiration`和`list_models`从ImgLume API读取数据。
- `enhance_prompt`向当前MCP主机模型返回指导，不会调用单独的ImgLume AI模型。
- 图像和视频生成将提示和任何参考图像发送到ImgLume。
- 生成的资产下载到配置的本地输出目录中。
- 此MCP服务器不添加分析或遥测。
- 将`IMGLUME_API_KEY`视为密码。不要发布它、提交它或将其粘贴到共享日志中。
参见[ImgLume隐私政策](https://imglume.com/privacy)，了解服务的数据实践。
## 故障排除
### 工具未显示
确认已安装Node.js 20或更新版本，然后在更改MCP客户端配置后重启。
### 画廊搜索返回无结果
使用更短或更广泛的术语，或省略查询以浏览热门内容。
### 生成提示需要API密钥
在[ImgLume API密钥](https://imglume.com/settings/apikeys)处创建密钥，添加为`IMGLUME_API_KEY`, 然后重启客户端使其重新加载环境。
### 参考图像被拒绝
使用绝对的本地路径或返回JPG、PNG或WebP图像的公共URL。确认每个图像的大小不超过10 MB。
### 图像或视频生成超时
MCP服务器默认情况下最多等待5分钟的图像和15分钟的视频。MCP主机的请求超时必须至少与此一样长。根据需要增加主机超时或相应的`IMGLUME_*_TIMEOUT_MS`值。
### 无法找到生成的图像
完成的工具响应包括确切的保存路径。默认目录是`~/Pictures/imglume`；如果已覆盖，请检查`IMGLUME_OUTPUT_DIR`。
对于可复制的问题，请打开一个[GitHub问题](https://github.com/Hanyuyu/imglume-mcp/issues)，但不要包括您的API密钥。
## 可选技能
[`skills/visual-creative/SKILL.md`](skills/visual-creative/SKILL.md)为支持技能的主机提供轻量级指导。它保留了诸如产品图像、肖像、海报、角色、室内、缩略图和故事板等场景作为示例，而不是固定的工作流。
MCP服务器在没有技能的情况下也可以正常工作。
## 贡献
此公共仓库仅包含MCP层。私有ImgLume产品和API后端不属于贡献者设置。
```bash
git clone https://github.com/Hanyuyu/imglume-mcp.git
cd imglume-mcp
pnpm install
pnpm check
pnpm build
```
贡献者可以使用公共ImgLume API测试可读工具。生成测试需要他们自己的ImgLume账户、API密钥和积分。
## 许可证
[MIT](LICENSE)
