convez.ai
MCP ServerIntegração & APIsIntermediário
Kerry1020

Image MCP Worker

Kerry1020/image-mcp-worker

Gerador de imagens MCP multi-provedor em Cloudflare Workers

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-worker

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
2

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

  1. Fork this repo
  2. Create a KV namespace:
    wrangler kv namespace create IMAGE_KV
    
  3. 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
    
  4. Deploy:
    wrangler deploy
    

Configuration

All config can be set via env vars (deployment-level) or request headers (per-request override):

Env VarHeaderRequiredDefaultDescription
API_KEYX-API-Key✅—API key for your image provider
API_BASE_URLX-API-Base-URL✅—Provider base URL (e.g. https://api.example.com/v1)
MODELX-Model❌gpt-image-1Model 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

SizeAspect Ratio
1024x10241:1 (default)
1024x15362:3 (portrait)
1536x10243:2 (landscape)
autoProvider decides

Cloudflare KV Free Tier Limits

ResourceFree Limit
Reads100,000 / day
Writes1,000 / day (limits daily image generations)
Storage1 GB
List operations1,000 / day

Images auto-expire after 1 hour via TTL, so storage is self-cleaning.

License

MIT

Ver o original no GitHub

Bom para

Relacionados