Image MCP Worker
Kerry1020/image-mcp-worker
Gerador de imagens MCP multi-provedor em Cloudflare Workers
Ver no GitHubServidor MCP para geração de imagens via APIs compatíveis com OpenAI, hospedado em Cloudflare Workers. Suporta múltiplos provedores, armazenamento em cache via KV e acesso por download direto ou base64.
Instalação
npx convez-ai Kerry1020/image-mcp-worker1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar geração de imagens em fluxos MCP com Claude
- Criar aplicações serverless de geração de arte com cache automático
- Oferecer múltiplos modelos de imagem com credenciais por requisição
Veredito

Solução robusta para exposição de APIs de geração de imagem via MCP em infraestrutura serverless. Bem documentada e pronta para produção, com suporte a multi-tenant e cache automático. Recomendado para quem integra geração de imagens em sistemas MCP.
README
A tradução para o português deste README ainda está na fila.
image-mcp-worker
An MCP (Model Context Protocol) compatible image generation worker that runs on Cloudflare Workers. Generate images from text prompts with direct download URLs and base64 support.
Features
- MCP Protocol — Streamable HTTP / JSON-RPC 2.0, works with any MCP client
- Bring Your Own Provider — Pass any OpenAI-compatible image API via headers or env vars
- Direct Download URLs — Generated images served as raw PNG via
/img/{id}.png - Base64 JSON — Also available via
/img/{id}.png?format=b64 - Cloudflare KV Storage — Images cached 1 hour, auto-expiring
- Multi-tenant Ready — Per-request header overrides for API key, base URL, and model
Quick Start
Deploy to Cloudflare Workers
- Fork this repo
- Create a KV namespace:
wrangler kv namespace create IMAGE_KV - Set your secrets:
wrangler secret put API_KEY wrangler secret put API_BASE_URL # e.g. https://your-provider.com/v1 wrangler secret put MODEL # optional, default: gpt-image-1 - Deploy:
wrangler deploy
Configuration
All config can be set via env vars (deployment-level) or request headers (per-request override):
| Env Var | Header | Required | Default | Description |
|---|---|---|---|---|
API_KEY | X-API-Key | ✅ | — | API key for your image provider |
API_BASE_URL | X-API-Base-URL | ✅ | — | Provider base URL (e.g. https://api.example.com/v1) |
MODEL | X-Model | ❌ | gpt-image-1 | Model name |
Priority: header > env var > default
This means you can deploy with env vars for your own use, and also let other users pass their own credentials via headers.
API Endpoints
POST /mcp — MCP Protocol
Standard MCP Streamable HTTP endpoint. Supports initialize, tools/list, tools/call, ping.
Tool: generate_image
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "A samurai cat in a neon-lit cyberpunk city",
"size": "1024x1024"
}
}
}
Response includes both a download URL and inline base64:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "✅ Image generated (1024x1024, gpt-image-1)\n\nDownload URL: https://your-worker.example.com/img/abc123.png\n\nDirect link valid for 1 hour.\nBase64 JSON: https://your-worker.example.com/img/abc123.png?format=b64"
},
{
"type": "image",
"data": "iVBORw0KGgo...",
"mimeType": "image/png"
}
]
}
}
With per-request headers (multi-tenant):
curl -X POST https://your-worker.example.com/mcp \
-H "Content-Type: application/json" \
-H "X-API-Key: sk-your-key" \
-H "X-API-Base-URL: https://your-provider.com/v1" \
-H "X-Model: dall-e-3" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_image","arguments":{"prompt":"sunset over mountains"}}}'
GET /img/{id}.png — Direct PNG Download
Returns raw PNG binary. Valid for 1 hour after generation.
curl -o image.png https://your-worker.example.com/img/abc123.png
GET /img/{id}.png?format=b64 — Base64 JSON
Returns base64-encoded image as JSON:
{
"id": "abc123",
"mime_type": "image/png",
"data": "iVBORw0KGgo..."
}
POST /tools/generate_image — REST Endpoint (Legacy)
Non-MCP REST interface for simple integrations:
curl -X POST https://your-worker.example.com/tools/generate_image \
-H "Content-Type: application/json" \
-H "X-API-Key: sk-your-key" \
-H "X-API-Base-URL: https://your-provider.com/v1" \
-d '{"prompt":"a red panda eating bamboo","size":"1024x1024"}'
GET /health — Health Check
{
"ok": true,
"name": "image-mcp-worker",
"version": "3.0.0",
"tools": ["generate_image"],
"protocol": "MCP Streamable HTTP",
"endpoints": { ... }
}
Connect to MCP Clients
Claude Desktop / Claude Code
Add to your MCP client config:
{
"mcpServers": {
"image-gen": {
"url": "https://your-worker.example.com/mcp",
"headers": {
"X-API-Key": "sk-your-key",
"X-API-Base-URL": "https://your-provider.com/v1"
}
}
}
}
Hermes Agent
hermes mcp add image-gen --transport http --url https://your-worker.example.com/mcp \
--header "X-API-Key: sk-your-key" \
--header "X-API-Base-URL: https://your-provider.com/v1"
Supported Sizes
| Size | Aspect Ratio |
|---|---|
1024x1024 | 1:1 (default) |
1024x1536 | 2:3 (portrait) |
1536x1024 | 3:2 (landscape) |
auto | Provider decides |
Cloudflare KV Free Tier Limits
| Resource | Free Limit |
|---|---|
| Reads | 100,000 / day |
| Writes | 1,000 / day (limits daily image generations) |
| Storage | 1 GB |
| List operations | 1,000 / day |
Images auto-expire after 1 hour via TTL, so storage is self-cleaning.
License
MIT