Cloudflare Image MCP

OpenAI-compatible image generation API + Streamable HTTP MCP server powered by Cloudflare Workers AI.

🌟 Features

• OpenAI-Compatible API: /v1/images/generations + /v1/images/edits endpoints
• MCP Protocol Support: HTTP transport with SSE (streamable)
• 10 Image Generation Models: FLUX, SDXL, Stable Diffusion, and more
• Multiple Tasks: Text-to-image, image-to-image (masked edits supported)
• Web Frontend: Interactive UI for image generation
• Self-Hosted MinIO Storage: Replaces Cloudflare R2 with a self-hosted MinIO instance running on Docker/Coolify with automatic image expiry.

📦 What's Included

cloudflare-image-mcp/
├── workers/           # Cloudflare Worker (API + MCP + Frontend)
└── e2e/               # Playwright E2E tests

---

🚀 Quick Start

Prerequisites

1. Deploy this MCP server to your Cloudflare account (takes 5 minutes): 👉 Deployment Guide

2. Note your worker URL after deployment:

   https://cloudflare-image-workers.<your-subdomain>.workers.dev
   

3. If you set API_KEYS during deployment, you'll need the key for authentication.

MCP Client Configuration

Below are the configuration guides for different MCP clients. This server uses HTTP/SSE transport (not stdio) since it runs on Cloudflare Workers.

<details><summary>Claude Desktop</summary>

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cloudflare-image": {
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

If using API key authentication:

{
  "mcpServers": {
    "cloudflare-image": {
      "url": "https://your-worker.workers.dev/mcp?key=your-api-key"
    }
  }
}

</details>

<details><summary>Claude Code</summary>

Add the MCP server:

claude mcp add cloudflare-image https://your-worker.workers.dev/mcp

With API key:

claude mcp add cloudflare-image https://your-worker.workers.dev/mcp?key=your-api-key

</details>

<details><summary>Cursor</summary>

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

{
  "mcpServers": {
    "cloudflare-image": {
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

</details>

<details><summary>Cline</summary>

Open Cline → Click MCP Servers icon → Installed tab → Advanced MCP Settings

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "cloudflare-image": {
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

</details>

<details><summary>Other MCP Clients</summary>

This server implements the MCP HTTP/SSE transport. Configure your client with:

• Transport: HTTP/SSE (streamable)
• URL: https://your-worker.workers.dev/mcp
• Auth (if API_KEYS set): Add ?key=your-api-key to the URL

</details>

---

📖 Usage

OpenAI-Compatible API

curl -X POST "https://your-worker.workers.dev/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "@cf/black-forest-labs/flux-1-schnell",
    "prompt": "A beautiful sunset over mountains",
    "n": 1,
    "size": "1024x1024"
  }'

And it can be used for OpenWebUI's image generation feature and image edits feature:

MCP Tools

Available Tools:

• list_models - List all available models
• describe_model - Get model parameters and limits
• run_model - Generate images

Connect via MCP:

{
  "mcpServers": {
    "image-gen": {
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

Web Frontend

Open your worker URL in a browser for an interactive UI.

---

🎨 Supported Models

📋 Detailed Model Specifications → — Full parameter reference, feature comparison, and capability matrix.

Model	Tasks	Provider
FLUX.1 [schnell]	text-to-image	Black Forest Labs
FLUX.2 [klein]	text-to-image, image-to-image	Black Forest Labs
FLUX.2 [dev]	text-to-image, image-to-image	Black Forest Labs
SDXL Base 1.0	text-to-image, image-to-image (img2img + masked edits)	Stability AI
SDXL Lightning	text-to-image	ByteDance
Dreamshaper 8 LCM	text-to-image, image-to-image (img2img)	Lykon
Lucid Origin	text-to-image	Leonardo
Phoenix 1.0	text-to-image	Leonardo
SD 1.5 Img2Img	image-to-image (img2img)	Runway ML
SD 1.5 Inpainting	image-to-image (requires mask)	Runway ML

---

📚 Documentation

Document	Description
Deployment Guide	Step-by-step deployment instructions
MinIO Deployment Guide	Self-hosted MinIO & Coolify deployment instructions
Credentials Setup	Environment variables and API tokens
Usage Guide	Detailed API usage examples
MCP Guide	MCP protocol and tools reference
API Reference	REST endpoints documentation

---

🧪 Testing

# Run E2E tests against staging/production
npm run test:e2e:staging
npm run test:e2e:production

---

🔧 Development

# Type check
npm run build

# Run E2E tests
npm run test:e2e:staging

---

📝 License

MIT

---

Built with:

• Cloudflare Workers AI
• MinIO / S3 Object Storage (Self-hosted replacement for R2)
• Model Context Protocol

Credits: Migrated to self-hosted MinIO S3 from the original project: tan-yong-sheng/cloudflare-image-mcp.