Image-Generation-MCP

An MCP (Model Context Protocol) stdio server that generates images from text prompts via api.airforce. It exposes a single generate_image tool, an image-models://list resource for model discovery, and runs over stdio so it works with any MCP-aware agent (Claude Desktop, Claude Code, Cursor, Cline, Hermes, etc.).

---

Features

• generate_image tool — text-to-image via the OpenAI-compatible /v1/images/generations endpoint.
• Model discovery resource — image-models://list returns the live list of image-capable model IDs from /v1/models, cached for 5 minutes.
• Format-aware data URLs — data[0].b64_json is wrapped as data:image/<fmt>;base64,... with the actual format (jpeg/png/webp/gif/bmp) sniffed from the payload, not hardcoded.
• Zero-config transport — stdio only, no HTTP port to manage.

---

One-click install

This repo ships a .mcp.json at the root. Most MCP clients (Claude Code, Cursor, Cline, Continue, Hermes) auto-discover it.

1. Set the API key

Get a key at https://api.airforce/ and export it:

# Linux / macOS
export AIRFORCE_API_KEY="sk-air-..."

# Windows PowerShell
$env:AIRFORCE_API_KEY = "sk-air-..."

Or copy .env.example to .env and fill it in — the server loads .env automatically when python-dotenv is installed (it is, as a dependency).

2. Run

The package is published on PyPI as image-generation-mcp. No manual install needed — the client invokes it via uvx:

uvx image-generation-mcp

uv will create an ephemeral venv, install the package, and run the server's console entry point on first use.

---

Client configuration

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": ["image-generation-mcp"],
      "env": {
        "AIRFORCE_API_KEY": "sk-air-..."
      }
    }
  }
}

Claude Code / Cursor / Cline (project-level)

A .mcp.json is already provided at the repo root:

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": ["image-generation-mcp"],
      "env": { "AIRFORCE_API_KEY": "${env:AIRFORCE_API_KEY}" }
    }
  }
}

The ${env:AIRFORCE_API_KEY} syntax delegates to the parent shell — set the env var once in your shell rc and every project picks it up.

Hermes / generic MCP client

Hermes and other stdio-MCP clients need the same shape: a command, args, and optional env. Point them at uvx with image-generation-mcp as the only arg, and pass AIRFORCE_API_KEY in the env block.

Local development (run from a checkout)

When hacking on the server itself, run it from the repo root:

{
  "mcpServers": {
    "image-generation": {
      "command": "uv",
      "args": ["run", "--project", ".", "image-generation-mcp"],
      "env": { "AIRFORCE_API_KEY": "sk-air-..." }
    }
  }
}

This uses the local pyproject.toml instead of the published package, so edits to server.py take effect on the next client restart.

---

Environment variables

Variable	Required	Description
AIRFORCE_API_KEY	Yes	Bearer token for api.airforce. Get one at https://api.airforce/.

If the key is missing, generate_image raises a clear error at call time instead of failing deep inside the HTTP layer.

---

Tools

generate_image

Generate a single image from a text prompt.

Arguments

Name	Type	Required	Description
model	string	Yes	Image model ID, e.g. flux-2-dev, nano-banana-pro.
prompt	string	Yes	Text description of the desired image.
aspect_ratio	string	No	1:1, 16:9, or 9:16. Some models support more — see image-models://list and the upstream docs.

Returns — the upstream JSON envelope, with data[].b64_json rewritten as a data:image/<fmt>;base64,... URL. The format is detected from the decoded magic bytes, so it is accurate for jpeg, png, webp, gif, and bmp payloads.

Example agent call

generate_image({
  "model": "flux-2-dev",
  "prompt": "A cute baby sea otter floating on its back, golden hour",
  "aspect_ratio": "16:9"
})

---

Resources

image-models://list

Returns a JSON list of every image-generation model ID currently available on api.airforce, filtered to entries whose media_type == "image". Cached for 5 minutes. Read this before calling generate_image to discover which model values are valid right now.

{
  "models": ["flux-2-dev", "nano-banana-pro", "..."],
  "count": 42
}

---

Prompts

summarize

A generic "summarize this text" prompt. Useful as a sanity check that the prompt channel is wired up; not specific to image generation.

---

Local development

# Clone and set up
git clone https://github.com/PurinNyova/Image-Generation-MCP.git
cd Image-Generation-MCP
uv sync
cp .env.example .env       # then fill in AIRFORCE_API_KEY

# Run the server
uv run image-generation-mcp

# Or run the bare module (no console script)
uv run python server.py

The server logs to stderr only — stdout is reserved for the MCP JSON-RPC stream, so any stray print will break the protocol.

Manual upstream tests

test_scripts/ is excluded from git but contains two diagnostic harnesses that exercise the api.airforce endpoints directly, independent of MCP:

# List image models
uv run python test_scripts/test.py

# Generate one image and write it to disk (auto-detects format)
uv run python test_scripts/image-generation-test.py

Override the test inputs via env vars: TEST_MODEL, TEST_PROMPT, TEST_ASPECT_RATIO, TEST_OUTPUT_PATH.

---

License

MIT. See LICENSE.