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)

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-email-mcp	IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g...	MCP
better-notion-mcp	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
claude-plugins	Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...	Marketplace
imagine-mcp	Image and video understanding + generation for AI agents -- across Gemini, Op...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Shared foundation for building MCP servers -- Streamable HTTP transport, OAut...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
tacet	TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn...	Tooling
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP server for AI agents: web search, content extraction, and lib...	MCP

Table of contents

• Features
• Install
• Smithery
• Configuration
• CLI
• Hosted endpoint
• 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.

Env var	Provider	Get a key at
GEMINI_API_KEY	Gemini (image + video)	aistudio.google.com/apikey
OPENAI_API_KEY	OpenAI (image)	platform.openai.com/api-keys
XAI_API_KEY	Grok / xAI (image + video)	console.x.ai

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.

Env var	Purpose
UNDERSTAND_MODELS	Ordered model chain for understand (litellm fallback). Empty and no explicit model -> understand fails loud (no built-in default).
GENERATE_MODELS	Ordered model chain for generate. The first entry selects the native provider + model. Empty -> the provider's own minimal built-in default.
GENERATE_PROVIDER_PRIORITY	CSV of provider names reordering generation auto-fallback. Defaults to grok,openai,gemini.

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

Invocation	Equivalent env	Result
imagine-mcp	MCP_TRANSPORT unset	stdio, single-user, env-var credentials
imagine-mcp --http	MCP_TRANSPORT=http (or TRANSPORT_MODE=http)	HTTP daemon -- local 127.0.0.1 self-host, or multi-user remote when PUBLIC_URL + MCP_DCR_SERVER_SECRET are set

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.

Hosted endpoint

A maintainer-run instance is live at https://imagine.n24q02m.com/mcp for 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 that URL and complete the OAuth flow to connect. Prefer to run your own? 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

Tool	Actions	Description
understand	--	Describe or reason over one or more image/video URLs. media_urls: list[str], prompt: str, provider, tier, max_tokens.
generate	--	Generate an image or video from a text prompt. media_type: image|video, optional reference_image_url, optional job_id (video poll), aspect_ratio, duration_seconds.
config	setup_status, setup_skip, setup_reset, setup_complete, warmup, status, set, cache_clear (relay_status/relay_skip/relay_reset/relay_complete honored as deprecated aliases)	Credential + runtime config: check credential state, set runtime knobs (log level, default provider, TTL), clear response cache.
help	--	Full Markdown documentation for understand, generate, or config topics.
config__open_relay	--	Framework-injected helper (mcp-core); opens the browser credential form.

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:

Capability	imagine-mcp	EverArt MCP	fal.ai MCP	Replicate Flux MCP
Image/video understanding	Yes (describe / classify / reason over image + video URLs)	No	No	No
Image generation	Yes (text-to-image + image-to-image via reference_image_url)	Yes (single generate_image)	Yes (text/image-to-image, edit, inpaint)	Yes (single generate_image)
Video generation	Yes (text-to-video + image-to-video, async job_id poll)	No	Yes (text/image-to-video)	No
Multi-provider backends	Yes (Gemini / OpenAI / Grok, auto-fallback)	No (EverArt only)	No (fal.ai only)	No (Replicate Flux only)
Quality/cost tiers	Yes (poor cheap-fast vs rich high-quality per provider)	No	No	No
Self-hostable / open source	Yes (MIT, stdio + HTTP self-host)	Yes (MIT, archived)	Yes (MIT)	Yes (MIT, archived)

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.

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.

Mode	Storage	Encryption	Who can read your data?
stdio (default)	~/.imagine-mcp/config.json	AES-GCM, machine-bound key	Only your OS user (file perm 0600)
HTTP self-host	Same as stdio	Same	Only you (admin = user)

Contributing

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

License

MIT -- see LICENSE.