AI图像处理工具

PixelForge MCP

An MCP server for AI-powered image generation, editing, analysis, and transformation using Google's Gemini image models.

Features

• 19 MCP tools for image generation, editing, analysis, transformation, and more
• 4 stable Gemini image models (Nano Banana 2.1, 2 Lite, 2, and Pro) plus configurable analysis models
• Quality presets (fast/balanced/quality) for simplified model selection
• Parallel multi-image generation via asyncio.gather
• Image transforms — crop, resize, rotate, flip, blur, sharpen, grayscale, watermark
• Prompt template library — 24 curated templates across 10 categories
• Generation history — full audit trail with search and pagination
• Batch processing — generate up to 10 images in parallel
• Generative upscale and mode-driven editing — upscale to the next 1K/2K/4K tier, inpaint, outpaint, background swap, style transfer, product shots
• Two backends — Gemini API key, or Vertex AI with a service account / Application Default Credentials
• Thinking mode & grounding — extended reasoning and Google Search for analysis
• 14 aspect ratios (including panoramic) and temperature control
• Async-first architecture with full Pydantic validation
• EXIF metadata embedding (prompt, model, timestamp)

Quick Start

Requirements: Python 3.10+ and a Google API key or a Google Cloud project with Vertex AI (see Authentication)

Install

pipx install pixelforge-mcp

Configure

Claude Code

claude mcp add pixelforge --scope user -e GOOGLE_API_KEY="your-key" -- pixelforge-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pixelforge": {
      "command": "pixelforge-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-key"
      }
    }
  }
}

VS Code

code --add-mcp '{"name":"pixelforge","command":"pixelforge-mcp","env":{"GOOGLE_API_KEY":"your-key"}}'

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pixelforge": {
      "command": "pixelforge-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-key"
      }
    }
  }
}

Kiro

kiro-cli mcp add --name pixelforge --scope global --command pixelforge-mcp --env "GOOGLE_API_KEY=your-key"

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pixelforge": {
      "command": "pixelforge-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Use

Ask Claude to generate, edit, or analyze images — all 19 tools are available automatically.

Authentication

PixelForge talks to Google through one of two backends. Every tool runs on either.

Gemini API key

Set any one of these variables. Get a key at Google AI Studio.

Vertex AI

Use a Google Cloud project with the Vertex AI API enabled and Application Default Credentials: a service account key file, gcloud auth application-default login, or the attached identity when running on Google Cloud. The identity needs the Vertex AI User role (roles/aiplatform.user). No extra packages are required.

{
  "mcpServers": {
    "pixelforge": {
      "command": "pixelforge-mcp",
      "env": {
        "GOOGLE_CLOUD_PROJECT": "my-project",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Backend selection

• An API key selects the Gemini API.
• GOOGLE_CLOUD_PROJECT with no API key selects Vertex AI.
• Both set: the API key wins unless GOOGLE_GENAI_USE_VERTEXAI=true.

get_server_info reports the active backend under backend.name.

Available Tools

Generation

Analysis

Analysis tools and optimize_prompt accept a model override. The default is gemini-3.5-flash-lite; use gemini-3.8-flash for harder OCR or reasoning.

Utility

History

Model Selection

PixelForge supports per-request model switching with 4 stable Gemini image models:

Image Models

gemini-2.5-flash-image is deprecated (Google has announced its shutdown) and remains only for existing setups. Use gemini-3.1-flash-lite-image instead.

0.5K is gemini-3.1-flash-image only and is sent to the API as 512px. generate_image rejects a size the chosen model cannot output.

upscale_image and advanced_edit re-render with gemini-nano-banana-2.1 unless model is set. upscale_image outputs the smallest of 1K/2K/4K that covers the source times the factor (capped at 4K) and needs a model with 2K/4K output (gemini-nano-banana-2.1, gemini-3.1-flash-image, or gemini-3-pro-image); gemini-3.1-flash-lite-image is rejected. Both tools pin the nearest aspect ratio the model supports; models without panoramic output get a standard ratio and a warning.

Analysis Models (text)

Used by analyze_image, extract_text, detect_objects, compare_images, and optimize_prompt. Override per request with model=.

Quality Presets

Instead of choosing a model manually, use quality presets:

generate_image(prompt="...", quality="fast")      # gemini-3.1-flash-lite-image
generate_image(prompt="...", quality="balanced")   # gemini-nano-banana-2.1 + 1K
generate_image(prompt="...", quality="quality")    # gemini-3-pro-image + 2K

Supported Aspect Ratios

* Panoramic ratios require gemini-nano-banana-2.1 or gemini-3.1-flash-image

Troubleshooting

"Invalid API key" or "Authentication failed"

Double-check your Google API key is correct and has access to the Gemini API. Get a key at Google AI Studio.

"Command not found: pixelforge-mcp"

Ensure the pipx bin directory is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

"Server not starting"

Check that pixelforge-mcp is installed:

pipx list | grep pixelforge

"Publisher model ... was not found" (Vertex AI)

With a regional location in the message, the request went to a regional Vertex AI endpoint. The current Gemini image and text models are served from the global endpoint: set GOOGLE_CLOUD_LOCATION=global (the default) or remove a regional override. With locations/global in the message, the model ID is unknown or retired on Vertex AI (list_available_models lists current IDs), or the project cannot access it yet. The same 404 is returned for retired Imagen model IDs, which PixelForge no longer calls.

"Rate limit exceeded" or "Permission denied"

The message carries Google's own text. A quota limit: 0, or "has not been used in project ... or it is disabled", is a project setup limit rather than a model problem: enable the Vertex AI API (or the Generative Language API for an API key), grant roles/aiplatform.user, or request a quota increase.

"No credentials found"

Set an API key, or GOOGLE_CLOUD_PROJECT with Application Default Credentials. See Authentication.

Documentation

• Configuration Guide — detailed setup and environment options
• Changelog — version history

Contributing

See CONTRIBUTING.md for development setup, code standards, and pull request guidelines.

License

AGPL-3.0

Acknowledgments

Built with FastMCP, Pydantic, and google-genai.

Author

Ahmed Al-Eryani @ Tehnolabs

PixelForge MCP - Forging pixels with AI