# ImgLume MCP

[![CI](https://github.com/Hanyuyu/imglume-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Hanyuyu/imglume-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](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 |
| --- | --- | --- |
| ![A fictional LUME NO. 7 perfume bottle created through ImgLume MCP](assets/lume-product.webp) | ![An adult fashion model holding the same LUME NO. 7 bottle](assets/lume-model.webp) | ![A stable frame from the generated model campaign video](assets/lume-video-frame.webp) |

[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.

![Four distinct campaigns generated from one product reference](assets/lume-four-directions.webp)

### 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.

![Product reference, model reference, and combined campaign output](assets/lume-dual-reference.webp)

### 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.

![A minimal perfume poster with exact requested headline and product text](assets/lume-exact-text.webp)

### 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.

![Four frames showing identity and product continuity across the generated video](assets/lume-video-continuity.webp)

[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)