imagine-mcp

mcp-name: io.github.n24q02m/imagine-mcp

Image and video understanding + generation for AI agents -- across Gemini, OpenAI, and Grok.

Sister projects from n24q02m (click to expand)

Table of contents

• Features
• Install
• Smithery
• Configuration
• CLI
• Remote (HTTP mode)
• Documentation
• Tools
• Comparison
• Security
• Build from Source
• Deploy to Cloudflare
• Trust Model
• Contributing
• License

Features

• Multimodal understanding -- Describe, classify, or reason over images and videos (Gemini handles mixed image + video in one call)
• Image generation -- Text-to-image and image-to-image (edit / inpaint) across Gemini Imagen, OpenAI gpt-image, Grok Imagine
• Video generation -- Text-to-video and image-to-video (Gemini Veo 3.1, Grok Imagine Video)
• 3 providers x 2 tiers -- Same interface for `gemini` / `openai` / `grok` at `poor` (cheap/fast) or `rich` (high quality); swap via parameter
• Open model passthrough -- Understanding routes through litellm; pass any `provider/model`, or configure an ordered model chain (no hardcoded catalog)
• Degraded mode -- Server starts with zero credentials and surfaces remaining providers as you add keys
• Response cache -- Disk-based caching of `understand` responses with configurable TTL
• Dual transport -- pure stdio with provider env vars (default) or HTTP multi-user with paste-token relay form

Install

Run with `uvx` (no install step) or pull the container image:

# uvx -- recommended, runs the published PyPI package
uvx imagine-mcp

# Docker
docker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest

Add it to an MCP client by pointing the client at the `uvx imagine-mcp` command and

supplying at least one provider key (see Configuration):

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": { "GEMINI_API_KEY": "AIza..." }
    }
  }
}

For per-client snippets (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and the

browser-based HTTP setup, see the Setup docs.

Install with an AI agent -- paste this to your AI coding agent:

> Install MCP server `imagine-mcp` following the steps at

> https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md

Smithery

imagine-mcp ships a `smithery.yaml` so it can be installed and

run through Smithery. The entry launches the published

PyPI package over stdio (`uvx --python 3.13 imagine-mcp`) with an empty config

schema -- no setup fields are required at deploy time. Provider keys are supplied

at runtime through the server's own credential flow (env vars in stdio mode, or

the browser setup form in HTTP mode; see Configuration).

Configuration

Two transports (default `stdio`; opt into `http` with `--http`, `MCP_TRANSPORT=http`,

or `TRANSPORT_MODE=http`):

• stdio (default) -- single-user, reads credentials from env vars only. Exits if

none of the three provider keys are set.

• http -- HTTP daemon. Local self-host on `127.0.0.1` by default, or multi-user

remote (per-JWT-sub credential isolation) when `PUBLIC_URL` + `MCP_DCR_SERVER_SECRET`

are set. In HTTP mode credentials are entered through a browser form at `/authorize`.

Provider keys

All optional -- the server starts in degraded mode and surfaces whichever providers

have a key. Set at least one.

When a tool is called without an explicit `provider`, the first key present wins in the

order `XAI_API_KEY` -> `OPENAI_API_KEY` -> `GEMINI_API_KEY`.

Model chains (optional)

Model choice passes straight through to litellm (`understand`) or the native

provider SDK (`generate`) -- there is no hardcoded model catalog. Each chain is a

CSV of litellm `provider/model` entries; the order is the fallback order.

Understanding is routed through litellm (`provider/model` passthrough), so any litellm

provider works -- supply that provider's `_API_KEY`. Generation stays on the

native provider SDKs (Gemini, OpenAI, Grok). Example:

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/,openai/",
        "GEMINI_API_KEY": "AIza...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Runtime knobs

`config(action="set", key=..., value=...)` adjusts `log_level`, `default_provider`,

`default_tier`, and `cache_ttl_seconds` at runtime.

CLI

The `imagine-mcp` console command installed by the package takes **no

subcommands** -- it starts the MCP server directly. Transport is selected by a

single flag or its environment-variable equivalents:

imagine-mcp            # stdio transport (default); reads provider keys from env vars
imagine-mcp --http     # HTTP daemon; credentials via the browser setup form

In stdio mode the server exits if none of the provider keys are set. The remote

HTTP bind knobs (`MCP_HOST`, `MCP_PORT`) apply only when `PUBLIC_URL` is set; see

Configuration.

Remote (HTTP mode)

An HTTP deployment serves clients that support remote HTTP MCP servers. It is

OAuth-gated -- an unauthenticated request returns `401` with a

`WWW-Authenticate: Bearer` challenge -- and credentials are provisioned through

the browser setup form. Point an HTTP-capable MCP client at

`https:///mcp` and complete the OAuth flow to connect.

To stand one up, see Deploy to Cloudflare.

Documentation

Full docs at **mcp.n24q02m.com/servers/imagine-mcp/setup/**:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio / local-relay / remote-relay / remote-oauth
• Multi-user setup -- per-JWT-sub credential model

Tools

Model choice is caller-driven (litellm `provider/model` passthrough or a `*_MODELS`

env chain) -- see Model chains above.

Comparison

How imagine-mcp stacks up against direct competitors in each pillar:

Security

• SSRF + LFI prevention -- All `media_urls` and `reference_image_url` are validated at the dispatch boundary; only `http://` and `https://` schemes reach the providers. `file://`, `ftp://`, `gopher://`, and scheme-less URLs are rejected.
• No credentials in errors -- Provider-side errors are sanitized before being returned.
• Degraded start -- Missing credentials do not prevent the server from starting; affected actions surface actionable errors instead of crashing at boot.
• Credential storage -- Credentials submitted through the browser credential form are stored encrypted via `mcp-core` (AES-GCM, machine-bound key) at `~/.imagine-mcp/config.json`.

Workspace username (HTTP setup form)

The browser credential form has an optional workspace username field. Entering

the same username always lands you in the same per-`sub` bucket, so your provider

keys stay reachable across a re-authorization and across devices, instead of being

tied to the one-off subject minted for each `/authorize` round-trip. Leaving it

blank keeps the previous per-authorize behaviour.

Trust boundary: when the form is gated by a *shared* `MCP_RELAY_PASSWORD`, the

username is a partition key, not a secret -- anyone who knows that password can

type any username and reach that bucket. That is fine for a trusted group; an

untrusted multi-tenant deployment needs a per-user secret or delegated OAuth

instead.

One-time migration: existing users must re-enter their credentials once after

this change. Nothing is deleted; credentials stored under the old random subject

are simply no longer addressed.

Build from Source

git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup      # or: uv sync --group dev
mise run dev        # run the server in stdio mode (add --http for the HTTP daemon)

Deploy to Cloudflare

Run your own imagine instance serverless on Cloudflare (Worker + Container + KV). Storage

is KV-only -- the per-user credential vault lives in KV, and generation returns base64 only

because the container filesystem is ephemeral (`IMAGINE_OUTPUT_MODE=base64`).

Prerequisites: a Cloudflare account on the Workers Paid plan -- required for Containers (the Cloudflare free tier does not include Containers) -- and the `wrangler` CLI.

1. `git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp`

2. `wrangler login`

3. Create the KV namespace (imagine is KV-only -- no D1 or Vectorize), then paste the

returned id into `wrangler.jsonc` (the `` placeholder):

wrangler kv namespace create imagine-kv

4. Push the container image to your Cloudflare managed registry (CF Containers cannot pull

from external registries directly), then set `` in `wrangler.jsonc`:

docker pull ghcr.io/n24q02m/imagine-mcp:beta
   docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta
   wrangler containers push imagine-mcp:beta   # prints registry.cloudflare.com//imagine-mcp:beta

5. Point the remaining `wrangler.jsonc` placeholders at your own domain: ``

(the `vars.PUBLIC_URL`, e.g. `https://imagine.example.com`) and ``

(the `routes` custom-domain pattern, e.g. `imagine.example.com`).

6. Set secrets. `CREDENTIAL_SECRET` (stable JWT signing key + per-user vault key) and

`MCP_DCR_SERVER_SECRET` (proof of an intentional multi-user deploy) are required;

`MCP_RELAY_PASSWORD` gates the browser setup form's login. Provider keys are optional

server defaults -- users normally paste their own through the setup form instead:

wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_DCR_SERVER_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put GEMINI_API_KEY       # optional provider default
   wrangler secret put OPENAI_API_KEY       # optional provider default
   wrangler secret put XAI_API_KEY          # optional provider default

7. `wrangler deploy`, then open your Worker domain and finish setup in the browser relay form.

The `http` container image already runs multi-user (`MCP_TRANSPORT=http` is baked into the

image target). Storage maps to Cloudflare via `MCP_STORAGE_BACKEND=cf-kv` (encrypted

credential vault) with `IMAGINE_OUTPUT_MODE=base64`, which forces base64 responses so no

media path is written to the ephemeral container filesystem.

Trust Model

This plugin implements TC-Local (machine-bound, single trust principal). See mcp-core trust model for full classification.

Contributing

See CONTRIBUTING.md for the full development workflow, commit convention, and release process. Issues + Discussions welcome.

License

Apache-2.0 -- see LICENSE.