Imagine MCP

ARCHIVED 2026-09-13 — This repository is no longer maintained. Use your image provider's native API instead of this MCP server. Existing installations keep working but receive no updates or support.

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
• Deployment
• 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/](https://mcp.n24q02m.com/servers