convez.ai
MCP ServerDesign & UIAvançado
FloLey

Image Studio MCP

FloLey/image-mcp

Geração de imagens Gemini com controle de acesso e dashboard de custos

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para geração de imagens com modelos Gemini do Google, com interface web autenticada por OAuth. Permite que grupos pequenos gerem imagens sob controle de custo, com dashboard para monitorar uso e preço estimado de cada geração.

Instalação

$npx convez-ai FloLey/image-mcp

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
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Geração de imagens iterativas para prototipagem visual
  • Criação de ilustrações e renders de diferentes qualidades
  • Monitoramento centralizado de custos de geração entre usuários
  • Integração de geração de imagens em fluxos de trabalho com Claude

Veredito

Solução robusta e production-ready para equipes que precisam gerar imagens sob demanda com rastreamento rigoroso de custos. Implementação bem estruturada com autenticação segura, mas requer hospedagem própria e configuração de OAuth do Google.

README

A tradução para o português deste README ainda está na fila.

Image Studio MCP

An MCP server that lets Claude (or any MCP client) generate images with Google's Gemini image models ("nano banana"). It is designed to be shared with a small group: anyone can connect with their Google account, but only the email addresses in IMG_ALLOWED_EMAILS can actually generate. It also ships a small web dashboard to browse what everyone generated and track the estimated cost.

It is a standalone Python service: a Docker image, an HTTP MCP endpoint, and a named volume for the generated images. Run it on any host that can sit behind a TLS-terminating reverse proxy.

What it does

A single MCP tool:

  • generate_image(prompt, aspect_ratio?, reference_images?, model?, image_size?) generates a PNG, stores it under the data volume with a random uuid name, and returns a small inline preview plus the full-size URL (https://YOUR_DOMAIN/i/{uuid}.png). Passing the filenames of previous generations as reference_images lets you iterate ("same scene but at night"); model picks flash or pro and image_size picks 1K/2K/4K.

Two models and three output sizes, chosen per request by use case (Google list prices per generated image):

AliasModel id1K2K4KUse for
flashgemini-3.1-flash-image-preview (Nano Banana 2)$0.067$0.101$0.151drafts, iterations, simple scenes
progemini-3-pro-image-preview (Nano Banana Pro)$0.134$0.134$0.24final renders, text in image, complex compositions

The model parameter accepts the alias, the full id, or the doc-page name (gemini-3.1-flash-image / gemini-3-pro-image). The tool contract tells the model to only pass it when the human explicitly asked for a specific model; otherwise the per-user default chosen in the /ui dashboard applies, falling back to flash. image_size is 1K (default), 2K, or 4K. Ids and prices are env-overridable (IMG_MODEL_FLASH, IMG_MODEL_PRO, IMG_COST_{FLASH|PRO}_{1K|2K|4K}), so a model rename or price change needs no code change.

Public routes (not tools): GET /health for the container healthcheck, and GET /i/{name} serving the generated PNGs (the unguessable uuid4 filename is the access control, and Claude.ai needs to fetch the URL to show the image).

Every generation writes a sidecar JSON ({uuid}.json, never served publicly) recording the caller's email, the prompt, the model and size used, the timestamp, and the estimated cost. That feeds the dashboard.

Web dashboard (/ui)

A browser-facing dashboard served by the same process at https://YOUR_DOMAIN/ui:

  • a cost per user table (image count + estimated cost, with a total);
  • a gallery per user (thumbnails, prompt, date, model, cost per image);
  • a "My default model" picker: each user chooses the model used when a generation does not specify one (stored in prefs.json in the data volume).

Auth: a browser Google login using the same OAuth client as the MCP endpoint, restricted to the allow-listed emails, with a signed HttpOnly/Secure session cookie. Emails in IMG_ADMIN_EMAILS see every user; other allow-listed users only see their own images and cost. The dashboard is read-only. In local dev (IMG_AUTH_DISABLED=1) the login is bypassed and everything is visible.

Authentication: Google OAuth + email allow-list

The server uses FastMCP's GoogleProvider (an OAuth proxy that runs the OAuth 2.1 + PKCE discovery flow Claude.ai expects). On top of "any valid Google login", AllowedEmailsMiddleware restricts tool calls to the emails in IMG_ALLOWED_EMAILS (comma-separated, case-insensitive).

Configuration (environment variables)

VariableRequiredPurpose
GEMINI_API_KEYyesthe image generation itself
GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRETyes (prod)OAuth login; the server refuses to start without them unless auth is disabled
IMG_PUBLIC_URLprodthe public base URL of the server, e.g. https://YOUR_DOMAIN
IMG_JWT_SIGNING_KEYrecommendedstable random value so issued tokens survive restarts (openssl rand -hex 32)
IMG_ALLOWED_EMAILSyes (prod)who may generate, e.g. me@gmail.com,friend@gmail.com
IMG_ADMIN_EMAILSnowho sees every user in the dashboard (others see only their own)
IMG_MODEL_FLASH / IMG_MODEL_PRO, IMG_COST_*nooverride model ids / estimated prices
IMG_ROOTnowhere images are stored (default /srv/images)
IMG_AUTH_DISABLED=1dev onlyrun open, no secrets needed

Provide these through your deployment's environment (a .env file, container secrets, an orchestrator, etc.). They are configuration, not committed to the repo.

Google OAuth client setup (one time)

In the Google Cloud console:

  1. Create (or reuse) a project, then APIs & Services -> OAuth consent screen: External, fill in the app name and contact email. The only scopes used are openid and userinfo.email (non-sensitive, no verification needed).
  2. While the consent screen is in Testing mode, add yourself and your friends as test users. This is a second gate on top of IMG_ALLOWED_EMAILS; alternatively, publish the app.
  3. APIs & Services -> Credentials -> Create credentials -> OAuth client ID, type Web application, with two authorized redirect URIs (Google matches them exactly, so both are needed):
    • https://YOUR_DOMAIN/auth/callback (MCP / Claude.ai)
    • https://YOUR_DOMAIN/ui/auth/callback (web dashboard)

Architecture

  • Transport: Streamable HTTP, MCP mounted at /mcp, listening on :8766.
  • Data: generated images live under IMG_ROOT (default /srv/images), intended to be a persistent volume so they survive restarts.
  • Public URL: https://YOUR_DOMAIN/mcp, behind a reverse proxy that terminates TLS (Caddy, nginx, Traefik, etc.).
image-mcp/
  Dockerfile
  pyproject.toml
  src/image_mcp/
    server.py    # FastMCP app: auth, middleware, tool, /health, /i/{name}
    access.py    # email allow-list logic (pure, unit-tested)
    storage.py   # uuid-named PNG storage under IMG_ROOT (pure, unit-tested)
    metadata.py  # per-generation sidecar JSON + per-user totals (pure, unit-tested)
    models.py    # flash/pro registry: ids, prices, alias resolution (pure, unit-tested)
    prefs.py     # per-user default model in prefs.json (pure, unit-tested)
    generate.py  # the Gemini call + inline preview downscale
    ui.py        # /ui dashboard: Google browser login + galleries + costs + prefs
  tests/

Run locally

The fast way, with auth disabled (no OAuth needed; generation still needs a real Gemini key):

docker build -t image-mcp .
docker run --rm -p 8766:8766 \
  -e IMG_AUTH_DISABLED=1 \
  -e GEMINI_API_KEY=your_key \
  -v "$PWD/.localdata:/srv/images" \
  image-mcp

Then:

curl -s localhost:8766/health        # -> {"ok": true}

npx @modelcontextprotocol/inspector
#   connect to: http://localhost:8766/mcp
#   call generate_image with a prompt

Tests

Pure-logic tests (allow-list, storage naming/path safety, model registry) need only pytest, no API key or network. They run in CI on every push.

pip install pytest        # or: pip install -e ".[dev]"
pytest -q

Deployment

The image is built from the included Dockerfile. A GitHub Actions workflow (.github/workflows/ci.yml) runs the tests and, on main, builds and pushes the image to GHCR. From there, deploy the container however you like: any Docker host works, as long as the MCP endpoint sits behind a reverse proxy that terminates HTTPS at your public URL and the env vars above are supplied.

Two things to remember in production:

  • mount a persistent volume at IMG_ROOT so generated images survive restarts;
  • point a DNS record for your domain at the host, and let the reverse proxy handle the certificate.

Connect Claude.ai

  1. In Claude.ai: Settings -> Connectors -> Add custom connector.
  2. URL: https://YOUR_DOMAIN/mcp.
  3. Claude redirects to Google to log in and consent. Any Google account can log in (if a test user, or once the app is published), but only allow-listed emails can call the tool.
  4. Others do the same from their own Claude accounts: send them the URL and make sure their email is in IMG_ALLOWED_EMAILS (and in the OAuth test users while the consent screen is in Testing mode).
Ver o original no GitHub

Bom para

Relacionados