imagine-mcp

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
• Configuration
• Documentation
• Tools
• Comparison
• Security
• Build from Source
• 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
• Leaderboard-ranked models -- Provider ordering auto-refreshed weekly from Artificial Analysis + LMArena leaderboards
• 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 andsupplying 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 thebrowser-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

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 ifnone of the three provider keys are set.
• http -- HTTP daemon. Local self-host on 127.0.0.1 by default, or multi-userremote (per-JWT-sub credential isolation) when PUBLIC_URL + MCP_DCR_SERVER_SECRETare 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 providershave a key. Set at least one.

When a tool is called without an explicit provider, the first key present wins in theorder XAI_API_KEY -> OPENAI_API_KEY -> GEMINI_API_KEY.

Model chains (optional)

Override the built-in provider/tier catalog with explicit model chains. Each is a CSV oflitellm provider/model entries; the order is the fallback order.

Understanding is routed through litellm (provider/model passthrough), so any litellmprovider works -- supply that provider's <PROVIDER>_API_KEY. Generation stays on thenative provider SDKs (Gemini, OpenAI, Grok). Example:

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/gemini-3.1-pro-preview,openai/gpt-5.4",
        "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.

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 IDs per provider x action x tier are leaderboard-ranked; see docs/models.md (auto-regenerated from src/imagine_mcp/models.py).

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.

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)

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.