Skip to content

coinstax/invokeai-mcp-server

BranchesTags

Repository files navigation

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.

License: MIT

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

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:

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

Links

About

MCP server for InvokeAI - text-to-image generation, img2img refinement, and AI upscaling for Claude Code

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.1 - Workflow Fix Latest
Oct 12, 2025
+ 1 release

Packages

 
 
 

Contributors

Languages