invokeai-mcp-server 1.0.0

A Model Context Protocol server for InvokeAI image generation

InvokeAI MCP Server

A Model Context Protocol (MCP) server that integrates InvokeAI with Claude Code, enabling AI-powered image generation, transformation, and upscaling directly from your AI assistant.

Overview

This MCP server provides a seamless bridge between Claude Code and your local InvokeAI instance, enabling powerful image generation workflows without leaving your development environment. Perfect for creating logos, icons, illustrations, and other visual assets for your projects.

Features

• Text-to-Image Generation: Create images from natural language descriptions
• Image-to-Image Transformation: Refine, modify, or stylize existing images
• LoRA Support: Apply fine-tuned LoRA models for specialized styles (logos, illustrations, etc.)
• Full SDXL Support: Automatic detection and proper configuration for SDXL models with dual CLIP encoders
• VAE Override Support: Use external VAE models to fix incompatible built-in VAEs or optimize for specific use cases
• AI-Powered Upscaling: Enhance images to higher resolutions (2x-4x) using state-of-the-art Spandrel models
• Flexible Model Support: Compatible with Stable Diffusion 1.5, SDXL, and custom fine-tuned models
• Comprehensive Parameter Control: Fine-tune generation with width, height, steps, CFG scale, schedulers, and seeds
• Queue Management: Monitor and track InvokeAI processing status

Prerequisites

• InvokeAI: A running instance (v4.0+) accessible at http://127.0.0.1:9090 (or custom URL)
• Claude Code: Anthropic's Claude CLI tool installed and configured
• Python: Version 3.8 or higher
• Hardware: GPU with sufficient VRAM for your chosen models (see Model Requirements)

Installation

Option 1: Install from PyPI (Recommended)

The easiest way to install the InvokeAI MCP server:

pip install invokeai-mcp-server

Then register with Claude Code:

# Linux/macOS/WSL
claude mcp add --scope user invokeai python -m invokeai_mcp_server

# Windows
claude mcp add --scope user invokeai python -m invokeai_mcp_server

Option 2: Install via Smithery

Install using the Smithery CLI for automatic configuration:

npx @smithery/cli install invokeai --client claude

Option 3: Install from Source

For development or customization:

# Clone the repository
git clone https://github.com/coinstax/invokeai-mcp-server.git
cd invokeai-mcp-server

# Run the automated setup script
./setup.sh

Or manually:

# Clone the repository
git clone https://github.com/coinstax/invokeai-mcp-server.git
cd invokeai-mcp-server

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

For Source Installation Only

If you installed from source, register with Claude Code:

Linux/WSL/macOS:

claude mcp add --scope user invokeai \
  ~/invokeai-mcp-server/venv/bin/python \
  ~/invokeai-mcp-server/invokeai_mcp_server.py

Windows:

claude mcp add --scope user invokeai ^
  C:\path\to\invokeai-mcp-server\venv\Scripts\python.exe ^
  C:\path\to\invokeai-mcp-server\invokeai_mcp_server.py

Verify Installation

claude mcp list

Expected output:

invokeai: ... - ✓ Connected

After registration, restart Claude Code or start a new conversation to access the tools.

Usage

Available Tools

generate_image

Generate images from text prompts with optional LoRA support.

Parameters:

• prompt (string, required): Description of the image to generate
• negative_prompt (string, optional): Elements to avoid in the generation
• width (integer, optional, default: 512): Image width (64-2048px)
• height (integer, optional, default: 512): Image height (64-2048px)
• steps (integer, optional, default: 30): Denoising steps (1-150)
• cfg_scale (float, optional, default: 7.5): Guidance scale (1.0-20.0)
• scheduler (string, optional, default: "euler"): Sampling scheduler
• seed (integer, optional): Random seed for reproducibility
• model_key (string, optional): Specific model identifier
• lora_key (string, optional): LoRA model identifier for fine-tuned style control
• lora_weight (float, optional, default: 1.0): LoRA strength (0.0-2.0)
• vae_key (string, optional): VAE model identifier to override model's built-in VAE

Example:

Generate a minimalist tech logo with blue and white colors, geometric shapes, flat design

Example with LoRA:

Generate a professional logo using the logomkrdsxl LoRA with prompt: "tech startup logo, modern, clean"

img2img

Transform existing images using text guidance with optional LoRA support.

Parameters:

• image_path (string, required): Path to source image or image_name from previous generation
• prompt (string, required): Description of desired transformation
• negative_prompt (string, optional): Elements to avoid
• strength (float, optional, default: 0.75): Transformation strength (0.0-1.0)
• steps (integer, optional, default: 30): Denoising steps (1-150)
• cfg_scale (float, optional, default: 7.5): Guidance scale (1.0-20.0)
• scheduler (string, optional, default: "euler"): Sampling scheduler
• seed (integer, optional): Random seed for reproducibility
• model_key (string, optional): Specific model identifier
• lora_key (string, optional): LoRA model identifier for fine-tuned style control
• lora_weight (float, optional, default: 1.0): LoRA strength (0.0-2.0)
• vae_key (string, optional): VAE model identifier to override model's built-in VAE

Example:

Refine this logo with strength 0.6: /path/to/sketch.png
Prompt: professional polished logo, clean lines, modern aesthetic

Example with LoRA:

Transform logo.png with logomkrdsxl LoRA at strength 0.6 to make it more professional

upscale_image

Enhance image resolution using AI upscaling.

Parameters:

• image_path (string, required): Path to image or image_name from previous generation
• model_key (string, optional): Specific upscaling model (auto-selects if omitted)

Example:

Upscale this image to high resolution: generated_logo.png

list_models

List available models in your InvokeAI instance.

Parameters:

• model_type (string, optional, default: "main"): Model type (main, vae, lora, controlnet, embedding, spandrel_image_to_image)

Example:

List all available SDXL models

get_queue_status

Check InvokeAI processing queue status.

Parameters:

• queue_id (string, optional, default: "default"): Queue identifier

Model Requirements

VRAM Requirements

Model Type	Minimum VRAM	Recommended VRAM	Notes
SD 1.5	4GB	6-8GB	Faster generation, good for iteration
SDXL	8GB	12GB+	Higher quality, slower generation
Upscaling (Spandrel)	4GB	6GB+	Depends on source image resolution

Recommended Models

Base Models

Stable Diffusion XL (SDXL)

• Superior quality for detailed graphics and illustrations
• Better text rendering capabilities
• Ideal for final production assets
• Download from: Stability AI on HuggingFace

Stable Diffusion 1.5

• Faster generation for rapid prototyping
• Lower VRAM requirements
• Recommended: Dreamshaper, Realistic Vision

Specialized Models (LoRAs)

• Vector Illustration LoRA - Clean vector-style graphics
• Logo Maker 9000 SDXL - Purpose-built for logo generation
• Flat Design LoRAs - Modern UI/UX style illustrations

Model repositories:

• Civitai - Community models and LoRAs
• HuggingFace - Official Stability AI models

Note: FLUX models use a different architecture and may have limited compatibility with InvokeAI's workflow system. For best results, use SD 1.5 or SDXL-based models.

Workflow Examples

Logo Design Pipeline

1. Generate initial concept with LoRA (512x512, 25 steps, logomkrdsxl LoRA)
2. Refine with img2img + LoRA (strength 0.6-0.7)
3. Upscale to high resolution (4x)
4. Export final asset

LoRA Workflow

1. List available LoRAs: list_models(model_type="lora")
2. Generate with LoRA: generate_image(prompt="...", lora_key="...", lora_weight=1.0)
3. Experiment with weights: Try 0.5 (subtle), 1.0 (standard), 1.5 (strong)
4. Combine with img2img for iterative refinement

Rapid Prototyping

1. Generate variations (SD 1.5 for speed)
2. Select best candidate
3. Upscale to production resolution
4. Apply final refinements with img2img

Architecture

The server implements a graph-based workflow system that interfaces with InvokeAI's node architecture:

1. Model Loading - Initializes selected SD model and VAE
2. Prompt Encoding - Processes positive and negative prompts via CLIP
3. Latent Generation - Creates noise tensors with specified dimensions
4. Denoising - Iteratively refines latents using the diffusion process
5. Decoding - Converts latents to pixel space via VAE
6. Output - Saves final image to InvokeAI's storage

All workflows are automatically constructed and managed by the server based on the requested operation.

Troubleshooting

Server Not Connecting

Symptoms: MCP server doesn't appear in Claude Code tools list

Solutions:

1. Verify InvokeAI is running: curl http://127.0.0.1:9090/api/v1/app/version
2. Check server registration: claude mcp list
3. Restart Claude Code or start a new conversation
4. Check Python dependencies: pip install -r requirements.txt

Common Issues

Issue	Cause	Solution
Connection refused	InvokeAI not running	Start InvokeAI service
No models available	Models not installed	Install models via InvokeAI Model Manager
Import errors	Missing dependencies	Run pip install -r requirements.txt
Generation fails	Insufficient VRAM	Reduce image size or use SD 1.5
Upscaling fails	No Spandrel models	Install upscaling models in InvokeAI
SDXL + LoRA issues	Model incompatibility	Ensure LoRA base type matches SDXL model
Black images (SDXL)	Corrupt/missing VAE	Use VAE override: vae_key: "sdxl.vae" or vae_key: "sdxl-vae-fp16-fix"

Uninstalling

If installed via PyPI:

pip uninstall invokeai-mcp-server
claude mcp remove invokeai

If installed via Smithery:

smithery uninstall invokeai --client claude

If installed from source:

claude mcp remove invokeai

Development

Testing

Test the server directly:

python3 invokeai_mcp_server.py

The server will start in stdio mode, waiting for MCP protocol messages.

Project Structure

invokeai-mcp-server/
├── invokeai_mcp_server.py    # Main server implementation
├── requirements.txt           # Python dependencies
├── setup.sh                   # Automated setup script
├── README.md                  # Documentation
└── LICENSE                    # MIT License

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on the Model Context Protocol
• Powered by InvokeAI
• Integrated with Claude Code

Links

• Repository: https://github.com/coinstax/invokeai-mcp-server
• InvokeAI: https://github.com/invoke-ai/InvokeAI
• Model Context Protocol: https://modelcontextprotocol.io
• Issues: https://github.com/coinstax/invokeai-mcp-server/issues