imagine-mcp

# imagine-mcp

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

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

<!-- Badge Row 1: Status -->
[![CI](https://github.com/n24q02m/imagine-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/imagine-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/n24q02m/imagine-mcp/graph/badge.svg)](https://codecov.io/gh/n24q02m/imagine-mcp)
[![PyPI](https://img.shields.io/pypi/v/imagine-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/imagine-mcp/)
[![Docker](https://img.shields.io/docker/v/n24q02m/imagine-mcp?label=docker&logo=docker&logoColor=white&sort=semver)](https://hub.docker.com/r/n24q02m/imagine-mcp)
[![License: Apache-2.0](https://img.shields.io/github/license/n24q02m/imagine-mcp)](LICENSE)

<!-- Badge Row 2: Tech -->
[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)](#)
[![FastMCP](https://img.shields.io/badge/FastMCP-purple?logo=anthropic&logoColor=white)](#)
[![MCP](https://img.shields.io/badge/MCP-000000?logo=anthropic&logoColor=white)](#)
[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)
[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot&logoColor=white)](https://developer.mend.io/)

<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO -->
<details>
  <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

| Project | Tagline | Tag |
|---|---|---|
| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |
| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |
| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |
| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |

</details>
<!-- END: AUTO-GENERATED-CROSS-PROMO -->

## Table of contents

- [Features](#features)
- [Install](#install)
- [Smithery](#smithery)
- [Configuration](#configuration)
- [CLI](#cli)
- [Remote (HTTP mode)](#remote-http-mode)
- [Documentation](#documentation)
- [Tools](#tools)
- [Comparison](#comparison)
- [Security](#security)
- [Build from Source](#build-from-source)
- [Deploy to Cloudflare](#deploy-to-cloudflare)
- [Trust Model](#trust-model)
- [Contributing](#contributing)
- [License](#license)



<a href="https://glama.ai/mcp/servers/n24q02m/imagine-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/n24q02m/imagine-mcp/badge" alt="imagine-mcp server" />
</a>

## 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`](https://docs.astral.sh/uv/) (no install step) or pull the container image:

```bash
# 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](#configuration)):

```json
{
  "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](https://mcp.n24q02m.com/servers/imagine-mcp/setup/).

**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`](smithery.yaml) so it can be installed and
run through [Smithery](https://smithery.ai). 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)).

## 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:

```json
{
  "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

`co