imglume-mcp

# ImgLume MCP [](https://github.com/Hanyuyu/imglume-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org/) An open-source local MCP server that connects AI clients to [ImgLume](https://imglume.com) for visual inspiration, prompt improvement, image generation and editing, and video generation. The tools are flexible building blocks. Search the gallery when inspiration is useful, improve a short idea when needed, or generate directly when the user already knows what they want. ## How it works ```text MCP host (Codex, Claude Code, Cursor, ...) -> local ImgLume MCP server (this repository) -> ImgLume API -> generated files saved on your computer ``` This repository contains only the open-source MCP server. The ImgLume website and API backend are not included. Gallery prompts and model information are read from ImgLume's live catalog. New gallery entries, model options, and image or video credit costs can therefore become available without an MCP update. An MCP update is needed only when the tool or API contract changes. ## See it in action Every asset below came from one production run through the public MCP tools. The fictional `LUME NO. 7` product was created first, combined with a fashion model reference, and then animated from the saved local campaign image. | Create the product | Build a model campaign | Animate the campaign | | --- | --- | --- | |  |  |  | [Watch the 4-second generated video](assets/lume-model-video.mp4). ## Hard cases These are ordinary `generate_image` and `generate_video` calls rather than hard-coded workflows. They show how the same tools can handle several constraints at once. ### One reference, four visual directions The base bottle was used in four parallel image requests: fashion campaign, midnight neon, moonlit botanicals, and minimal editorial. The bottle geometry, purple-to-amber liquid, black cap, and gold label remain recognizable while the art direction changes.  ### Two references, one controlled composition Left to right: the product reference, the model reference, and a new campaign. The request preserved the model's identity, green dress, bottle design, and label while moving both subjects into a warm gold studio.  ### Exact poster copy This 9:16 poster required exactly two headline lines: `MIDNIGHT BLOOM` and `LUME NO. 7`, while preserving the three-line product label.  ### Image-to-video continuity Frames at 0.05, 1.30, 2.60, and 3.85 seconds show the same face, hairstyle, dress, hand pose, bottle, and label through a slow camera push-in and subtle subject motion.  [Watch the full 4-second continuity test](assets/lume-model-video.mp4). ## Requirements - Node.js 20 or newer - An MCP client that supports local `stdio` servers - An ImgLume account and API key only when generating images or videos Gallery search, inspiration details, prompt improvement, and model discovery do not require an API key. ## Quick start Add ImgLume to your MCP client: ```json { "mcpServers": { "imglume": { "command": "npx", "args": ["-y", "github:Hanyuyu/imglume-mcp"] } } } ``` Restart the client, then try: > Browse popular ImgLume inspiration and show me three different visual > directions. To enable image and video generation: 1. [Create an ImgLume API key](https://imglume.com/settings/apikeys). ImgLume will guide signed-out users through login first. 2. Add the key to the server's environment: ```json { "mcpServers": { "imglume": { "command": "npx", "args": ["-y", "github:Hanyuyu/imglume-mcp"], "env": { "IMGLUME_API_KEY": "imglume_your_key" } } } } ``` Keep the key in your private, local MCP configuration. Never commit it to a repository. ### Codex ```bash codex mcp add imglume -- npx -y github:Hanyuyu/imglume-mcp ``` Add `--env IMGLUME_API_KEY=imglume_your_key` before `--` when generation is needed. ### Claude Code ```bash claude mcp add --scope user imglume -- npx -y github:Hanyuyu/imglume-mcp ``` Add `-e IMGLUME_API_KEY=imglume_your_key` before `--` when generation is needed. ### Cursor Save the JSON configuration above using [Cursor's MCP configuration](https://docs.cursor.com/context/model-context-protocol): - `~/.cursor/mcp.json` for all projects - `.cursor/mcp.json` for one project Restart Cursor after saving the file. ## Try it Use natural-language requests. The host chooses the relevant tool. ### Find inspiration > Search ImgLume for poster inspiration and show me five options. Use short, broad search terms such as `poster`, `product`, `portrait`, `anime`, or `cinematic`. Leave the search empty to browse popular work. ### Improve a brief > Improve this into a production-ready image prompt: a glass of coffee on a > snowy mountain, editorial style. ### Generate an image > Generate a vertical luxury campaign for a fictional LUME NO. 7 perfume: > an adult East Asian fashion model in an emerald one-shoulder dress, warm > studio lighting, and the product label clearly readable. ### Edit an image > Use `/absolute/path/to/product.png` and `/absolute/path/to/model.png` as > references. Preserve the model's identity, dress, bottle shape, and label; > place them together in a warm gold studio. ### Animate an image > Turn `/absolute/path/to/campaign.png` into a four-second video. Add a subtle > turn, blink, hair movement, and slow camera push-in while keeping the face, > hands, bottle, and label stable. Preview rendering depends on the MCP host. Hosts without inline media support may show a URL instead of the image or video itself. ## Tools | Tool | Purpose | API key | | --- | --- | --- | | `search_gallery` | Search the live gallery for visual references and prompt examples | No | | `get_inspiration` | Retrieve the full prompt, media, recommendations, and attribution | No | | `enhance_prompt` | Ask the current host model to improve a short visual brief | No | | `list_models` | Read current models, options, defaults, and live credit costs | No | | `generate_image` | Generate or edit one image and save it locally | Yes | | `generate_video` | Generate one video and save it locally | Yes | Each tool can be used independently. Gallery search is optional inspiration, not a required step before generation. ## Generation inputs and outputs - Use `list_models` when model choice, supported options, or current costs matter. Avoid relying on a hard-coded model list. - Image costs are reported per generation. Video costs are reported per second, so multiply the selected rate by the requested duration. - Image generation and video generation consume credits from the ImgLume account associated with the API key. - Reference images may be public HTTP(S) URLs or local file paths. - Local paths should be absolute so the MCP process resolves the intended file. - JPG, PNG, and WebP reference images are supported. - Each reference image may be up to 10 MB, with at most five references per request. - The MCP validates the live model, quality, and aspect-ratio options before uploading local references. Partial uploads are removed when an upload or generation submission fails. - Video duration may be between 4 and 15 seconds. Available quality and aspect ratio values come from the live model catalog. - Generated files are saved to `~/Pictures/imglume` by default. Set `IMGLUME_OUTPUT_DIR` to use another save location. ## Configuration | Variable | Purpose | Default | | --- | --- | --- | | `IMGLUME_API_KEY` | ImgLume API key used for generation | None | | `IMGLUME_API_URL` | Advanced API origin override | `https://imglume.com` | | `IMGLUME_OUTPUT_DIR` | Where generated files are saved | `~/Pictures/imglume` | | `IMGLUME_POLL_INTERVAL_MS` | Generation status polling interval | `2000` (2 seconds) | | `IMGLUME_IMAGE_TIMEOUT_MS` | Image wait timeout | `300000` (5 minutes) | | `IMGLUME_VIDEO_TIMEOUT_MS` | Video wait timeout | `900000` (15 minutes) | Most users should leave `IMGLUME_API_URL` unset. It exists for ImgLume maintainers and trusted compatible API environments; it does not provide the private ImgLume backend for local development. The configured API origin receives the API key, prompts, and uploaded reference images. Only point `IMGLUME_API_URL` at an endpoint you trust. ## Privacy and security - `search_gallery`, `get_inspiration`, and `list_models` read data from the ImgLume API. - `enhance_prompt` returns guidance to the current MCP host model and does not call a separate ImgLume AI model. - Image and video generation send the prompt and any reference images to ImgLume. - Generated assets are downloaded to the configured local output directory. - This MCP server adds no analytics or telemetry. - Treat `IMGLUME_API_KEY` like a password. Do not publish it, commit it, or paste it into shared logs. See the [ImgLume Privacy Policy](https://imglume.com/privacy) for the service's data practices. ## Troubleshooting ### The tools do not appear Confirm that Node.js 20 or newer is installed, then restart the MCP client after changing its configuration. ### Gallery search returns no results Use a shorter or broader term, or omit the query to browse popular inspiration. ### Generation says an API key is required Create a key at [ImgLume API Keys](https://imglume.com/settings/apikeys), add it as `IMGLUME_API_KEY`, and restart the client so it reloads the environment. ### A reference image is rejected Use an absolute local path or a public URL that returns a JPG, PNG, or WebP image. Confirm that each image is no larger than 10 MB. ### Image or video generation times out The MCP server waits up to 5 minutes for images and 15 minutes for videos by default. The MCP host's own request timeout must be at least as long. Increase the host timeout or the corresponding `IMGLUME_*_TIMEOUT_MS` value when needed. ### The generated file cannot be found The completed tool response includes the exact saved path. The default directory is `~/Pictures/imglume`; check `IMGLUME_OUTPUT_DIR` if it was overridden. For reproducible problems, open a [GitHub issue](https://github.com/Hanyuyu/imglume-mcp/issues) without including your API key. ## Optional skill [`skills/visual-creative/SKILL.md`](skills/visual-creative/SKILL.md) provides lightweight guidance for hosts that support skills. It keeps scenarios such as product imagery, portraits, posters, characters, interiors, thumbnails, and storyboards as examples rather than fixed workflows. The MCP server works without the skill. ## Contributing This public repository contains the MCP layer only. The private ImgLume product and API backend are not part of the contributor setup. ```bash git clone https://github.com/Hanyuyu/imglume-mcp.git cd imglume-mcp pnpm install pnpm check pnpm build ``` Contributors can exercise the read-only tools against the public ImgLume API. Generation tests require their own ImgLume account, API key, and credits. ## License [MIT](LICENSE)