Pixelforge MCP
AI-powered image generation, editing, and analysis MCP server using Google's Gemini models
Installation
npx pixelforge-mcpAsk AI about Pixelforge MCP
Powered by Claude Β· Grounded in docs
I know everything about Pixelforge MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
| Tool | Description |
|---|---|
generate_image | Generate images from text (6 models, 14 aspect ratios, quality presets, parallel multi-image) |
edit_image | Modify existing images with text prompts |
remove_background | Remove image background (transparent or white) |
transform_image | Crop, resize, rotate, flip, blur, sharpen, grayscale, or watermark |
batch_generate | Generate up to 10 images in parallel from multiple prompts |
Analysis
| Tool | Description |
|---|---|
analyze_image | AI-powered image description with optional grounding |
extract_text | OCR β extract text with confidence levels |
detect_objects | Detect objects with bounding boxes |
compare_images | Compare 2-10 images for differences |
Utility
| Tool | Description |
|---|---|
optimize_prompt | Enhance prompts for better image generation (14 styles) |
estimate_cost | Calculate generation costs per model/operation |
list_templates | Browse 24 curated prompt templates across 10 categories |
apply_template | Fill a template with your subject for a ready-to-use prompt |
list_available_models | Model capabilities, speed, quality, and selection guidance |
get_server_info | Server configuration and status |
History
| Tool | Description |
|---|---|
list_history | Browse generation history with pagination and filtering |
get_generation_details | Get full details of a specific generation |
Vertex AI (Optional)
| Tool | Description |
|---|---|
upscale_image | Upscale images x2 or x4 (requires Vertex AI) |
advanced_edit | Inpainting, outpainting, background swap, style transfer (requires Vertex AI) |
Model Selection
PixelForge supports per-request model switching with 6 models:
Gemini Models (via Gemini API)
| Use case | Model | Why |
|---|---|---|
| Fast iterations | gemini-2.5-flash-image (default) | Cheapest, lowest latency |
| Panoramic & grounded | gemini-3.1-flash-image-preview | 1:4/4:1/1:8/8:1, web+image grounding |
| Max text fidelity | gemini-3-pro-image-preview | ~94% accuracy, complex multi-turn edits |
Imagen 4 Models (via Gemini API)
| Use case | Model | Why |
|---|---|---|
| Cost-effective batch | imagen-4.0-generate-001 | $0.04/img, excellent quality |
| Cheapest generation | imagen-4.0-fast-generate-001 | $0.02/img, fastest |
| Maximum quality | imagen-4.0-ultra-generate-001 | $0.06/img, best output |
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:
- Set up a Google Cloud project with Vertex AI enabled
- Set the environment variable:
GOOGLE_CLOUD_PROJECT=your-project-id - 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
| Ratio | Description |
|---|---|
1:1 | Square (default) |
16:9 | Widescreen landscape |
9:16 | Mobile portrait |
2:3 | Classic portrait |
3:2 | Classic landscape |
3:4 | Portrait |
4:3 | Traditional landscape |
4:5 | Instagram portrait |
5:4 | Medium format |
21:9 | Ultrawide |
1:4 | Tall panoramic* |
4:1 | Wide panoramic* |
1:8 | Extra tall panoramic* |
8:1 | Extra wide panoramic* |
* 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
Acknowledgments
Built with FastMCP, Pydantic, and google-genai.
Author
Ahmed Al-Eryani @ Tehnolabs
PixelForge MCP - Forging pixels with AI
