ImgLume MCP

An open-source local MCP server that connects AI clients to ImgLume 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

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.

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.

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:

{
  "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. ImgLume will guide signed-out users through login first.
2. Add the key to the server's environment:

{
  "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

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

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:

• ~/.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 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, 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 without including your API key.

Optional skill

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.

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