Content
# Cloudflare Image MCP
[](https://github.com/tan-yong-sheng/cloudflare-image-mcp/actions/workflows/deploy-workers.yml)
[](https://github.com/tan-yong-sheng/cloudflare-image-mcp/actions/workflows/deploy-ghcr.yml)
[](https://github.com/tan-yong-sheng/cloudflare-image-mcp/pkgs/container/cloudflare-image-mcp)
OpenAI-compatible image generation API + MCP server powered by Cloudflare Workers AI.
## 🌟 Features
- **OpenAI-Compatible API**: `/v1/images/generations` endpoint
- **MCP Protocol Support**:
- Stdio transport (local CLI)
- HTTP transport with SSE (streamable)
- **10 Image Generation Models**: FLUX, SDXL, Stable Diffusion, and more
- **Multiple Tasks**: Text-to-image, image-to-image, inpainting
- **Dual Deployment**: Local server or Cloudflare Workers
- **Web Frontend**: Interactive UI for image generation
- **R2 Storage**: Auto-expiring image storage with CDN
## 📦 Architecture
```
cloudflare-image-mcp/
├── packages/
│ ├── core/ # Shared library (models, AI client, storage)
│ └── local/ # Local deployment (stdio MCP + HTTP server + UI)
└── workers/ # Cloudflare Workers deployment (HTTP MCP + API + UI)
```
## 🚀 Quick Start
### Prerequisites
- Node.js 18+
- Cloudflare account (for API access)
- R2 bucket (for image storage)
### Local Development
1. **Install dependencies**
```bash
# Install all packages
cd packages/core && npm install && npm run build
cd ../local && npm install && npm run build
cd ../..
```
2. **Configure environment**
```bash
cd packages/local
cp .env.example .env
# Edit .env with your credentials
```
3. **Start the server**
```bash
npm run dev
```
The server will start on `http://localhost:3000` with:
- **Web UI**: http://localhost:3000/
- **OpenAI API**: http://localhost:3000/v1/images/generations
- **HTTP MCP**: http://localhost:3000/mcp
- **Stdio MCP**: `node dist/main.js --stdio`
### Docker Deployment
**Option 1: Docker Compose (Recommended)**
```bash
# Copy and configure environment
cp .env.example .env
# Edit .env with your credentials
# Start with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f
# Access at http://localhost:3000
```
**Option 2: Pre-built Image from GHCR**
```bash
docker pull ghcr.io/tan-yong-sheng/cloudflare-image-mcp:latest
docker run -d \
--name cloudflare-image-mcp \
-p 3000:3000 \
-e CLOUDFLARE_API_TOKEN=your_token \
-e CLOUDFLARE_ACCOUNT_ID=your_account_id \
-e S3_BUCKET=your_bucket \
-e S3_ENDPOINT=https://your_account.r2.cloudflarestorage.com \
-e S3_ACCESS_KEY=your_access_key \
-e S3_SECRET_KEY=your_secret_key \
ghcr.io/tan-yong-sheng/cloudflare-image-mcp:latest
```
### Cloudflare Workers Deployment
**Option 1: Manual Deployment**
```bash
cd workers
cp wrangler.toml.example wrangler.toml
# Edit wrangler.toml with your account details
npm run deploy
```
**Option 2: Automated CI/CD**
The repository includes automated deployment via GitHub Actions:
1. Add secrets to your GitHub repository:
- `CLOUDFLARE_API_TOKEN`
- `CLOUDFLARE_ACCOUNT_ID`
- `CDN_URL` (optional)
2. Push to main branch or trigger workflow manually
3. Workers automatically deployed to: `https://cloudflare-image-workers.*.workers.dev/`
See [CICD_DEPLOYMENT.md](CICD_DEPLOYMENT.md) for detailed setup instructions.
## 📖 Usage
### OpenAI-Compatible API
```bash
curl -X POST "http://localhost:3000/v1/images/generations" \
-H "Content-Type: application/json" \
-d '{
"model": "@cf/black-forest-labs/flux-1-schnell",
"prompt": "A beautiful sunset over mountains",
"n": 1,
"size": "1024x1024"
}'
```
### MCP Tools
**Available Tools:**
- `list_models` - List all available models
- `describe_model` - Get model parameters and limits
- `run_models` - Generate images
**Workflow:**
1. Call `list_models` to get available models
2. Call `describe_model(model_id)` to understand parameters
3. Call `run_models(model_id, prompt, ...)` to generate
### Web Frontend
Open http://localhost:3000/ in your browser for an interactive UI.
## 🎨 Supported Models
| 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, inpainting | Stability AI |
| SDXL Lightning | text-to-image | ByteDance |
| Dreamshaper 8 LCM | text-to-image, image-to-image | Lykon |
| Lucid Origin | text-to-image | Leonardo |
| Phoenix 1.0 | text-to-image | Leonardo |
| SD 1.5 Img2Img | image-to-image | Runway ML |
| SD 1.5 Inpainting | inpainting | Runway ML |
## 🧪 Testing
Run the verification script:
```bash
./test-verification.sh
```
This tests:
- Package builds
- File structure
- Core exports
- MCP tool definitions
- Model configurations
- Documentation
## 📚 Documentation
- [Usage Guide](docs/USAGE.md) - Detailed API usage
- [Deployment Guide](docs/DEPLOY.md) - Production deployment
- [Implementation Plan](docs/PLAN.md) - Architecture details
- [OpenAI API Spec](docs/api/openai_standard/image_endpoint.md) - API reference
## 🔧 Development
### Build all packages
```bash
# Core
cd packages/core && npm run build
# Local
cd packages/local && npm run build
# Workers (type check only)
cd workers && npm run check
```
### Run tests
```bash
./test-verification.sh
```
## 🌐 Deployment Options
| Option | Transport | Best For |
|--------|-----------|----------|
| **Local Server** | HTTP | Development, self-hosted |
| **Local CLI** | stdio | MCP clients (Claude Desktop) |
| **Docker** | HTTP | Production, containerized |
| **Cloudflare Workers** | HTTP + SSE | Production, serverless, global CDN |
### Automated Deployments
This repository includes CI/CD pipelines for automated deployments:
- **Cloudflare Workers** - Auto-deploys on push to main
- **GitHub Container Registry** - Builds and publishes Docker images
See [CICD_DEPLOYMENT.md](CICD_DEPLOYMENT.md) for setup instructions.
## 📝 License
MIT
## 🤝 Contributing
See [CONTRIB.md](docs/CONTRIB.md) for guidelines.
---
**Built with:**
- [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/)
- [Cloudflare R2](https://developers.cloudflare.com/r2/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- TypeScript + Node.js
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
markitdown
Python tool for converting files and office documents to Markdown.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.