PixelForge MCP

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

Features

• 21 MCP tools for image generation, editing, analysis, transformation, and more
• 6 models including Gemini image models and Imagen 4 family
• 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
• Optional Vertex AI — upscaling (x2/x4) and advanced editing modes
• 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

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 21 tools are available automatically.

Available Tools

Generation

Analysis

Utility

History

Vertex AI (Optional)

Model Selection

PixelForge supports per-request model switching with 6 models:

Gemini Models (via Gemini API)

Imagen 4 Models (via Gemini API)

Quality Presets

Instead of choosing a model manually, use quality presets:

generate_image(prompt="...", quality="fast")      # gemini-2.5-flash-image
generate_image(prompt="...", quality="balanced")   # gemini-3.1-flash-image-preview + 1K
generate_image(prompt="...", quality="quality")    # gemini-3-pro-image-preview + 2K

Vertex AI (Optional)

For advanced features like image upscaling and specialized editing modes:

1. Set up a Google Cloud project with Vertex AI enabled
2. Set the environment variable: GOOGLE_CLOUD_PROJECT=your-project-id
3. Install the Vertex AI dependency: pip install pixelforge-mcp[vertex]

PixelForge auto-detects Vertex AI credentials and unlocks upscale_image and advanced_edit tools.

Supported Aspect Ratios

* Panoramic ratios require gemini-3.1-flash-image-preview model

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

Vertex AI features not available

Ensure GOOGLE_CLOUD_PROJECT is set and google-cloud-aiplatform is installed:

pip install pixelforge-mcp[vertex]

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