imagine-mcp

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

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

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

Related MCP server: mcp-media-engine

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 <PROVIDER>_API_KEY. Generation stays on the native provider SDKs (Gemini, OpenAI, Grok). Example:

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/<model-id>,openai/<model-id>",
        "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://<your-host>/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 <imagine-kv-namespace-id> 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 <YOUR_ACCOUNT_ID> 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/<ACCOUNT_ID>/imagine-mcp:beta

5. Point the remaining wrangler.jsonc placeholders at your own domain: <YOUR_PUBLIC_URL> (the vars.PUBLIC_URL, e.g. https://imagine.example.com) and <YOUR_WORKER_DOMAIN> (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

MIT -- see LICENSE.