Flux Image MCP Server

March 17, 2025 · View on GitHub

A Model Context Protocol (MCP) server for generating and modifying images using Replicate's Flux models.

Features

  • 🖼️ Generate Images: Create images from text prompts using Flux models
  • 🔄 Modify Images: Transform existing images with text prompts
  • 🎭 Inpaint Images: Remove or replace specific elements in images using Flux Fill Pro
  • 🔗 Get Image URLs: Obtain shareable URLs for local images
  • 📂 List Images: Browse images stored in various directories

Prerequisites

  • Node.js 16 or higher
  • An API key from Replicate
  • An API key from ImgBB (for image hosting)

Installation

# Clone the repository
git clone https://github.com/yourusername/flux-image-mcp.git
cd flux-image-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Create a .env file in the root directory with the following variables:

REPLICATE_API_TOKEN=your_replicate_api_token
IMGBB_API_KEY=your_imgbb_api_key

You can also configure the following optional variables:

IMAGE_INPUT_DIR=/path/to/input/images
MODIFIED_IMAGES_DIR=/path/to/modified/images
GENERATED_IMAGES_DIR=/path/to/generated/images

If not specified, the server will use the following default paths:

  • Input images: ./images or ~/Downloads/flux-images-input
  • Modified images: ./modified_images or ~/Downloads/flux-images-modified
  • Generated images: ./images-from-prompt or ~/Downloads/flux-images-generated

Usage with Claude Desktop

  1. Open your Claude Desktop App configuration at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the Flux Image MCP server to your configuration:

{
  "mcpServers": {
    "flux-image": {
      "command": "node",
      "args": [
        "/absolute/path/to/flux-image-mcp/dist/index.js"
      ]
    }
  }
}
  1. Restart Claude Desktop

Usage with Cursor.ai

  1. Open Cursor Settings
  2. Navigate to Features > MCP
  3. Click "+ Add New MCP Server"
  4. Use the following settings:
    • Type: stdio
    • Name: flux-image
    • Command: node /absolute/path/to/flux-image-mcp/dist/index.js
  5. Click "Add"

Available Tools

1. Generate Image

Create an image from a text prompt.

Parameters:

  • prompt (required): Text description of the desired image
  • image_filename (optional): Custom filename for the generated image
  • negative_prompt (optional): Text describing what not to include
  • width (optional): Width of the generated image (default: 1024)
  • height (optional): Height of the generated image (default: 1024)

2. Modify Image

Modify an existing image using a text prompt.

Parameters:

  • image_path (required): Path to the image file to modify
  • modification_prompt (required): Text describing how to modify the image
  • output_filename (optional): Custom filename for the modified image
  • model (optional): Model to use ("flux-schnell" or "flux-pro", default: "flux-schnell")

3. Get Image URL

Obtain a shareable URL for a local image.

Parameters:

  • image_path (required): Path to the image file
  • upload_method (required): Method to use for uploading ('imgbb' or 'replicate')

4. List Images

List all images in a specific directory.

Parameters:

  • directory (required): Directory to list images from ('input', 'modified', or 'generated')

5. Inpaint Image

Remove or replace specific elements in an image using Flux Fill Pro.

Parameters:

  • image_path (required): Path to the image file to inpaint
  • prompt (required): Text describing what should fill the masked area
  • mask_path (optional): Path to an existing mask image (white areas will be inpainted)
  • mask_area (optional): Object defining area to inpaint {x, y, width, height}
  • target_colors (optional): Array of RGB color values to target for inpainting, e.g. [[0,255,0]]
  • color_tolerance (optional): Tolerance for color matching (0-255, default: 30)
  • negative_prompt (optional): Text describing what should NOT appear in the inpainted area
  • output_filename (optional): Custom filename for the inpainted image
  • guidance_scale (optional): Guidance scale for the model (default: 9.0)
  • strength (optional): Strength of the inpainting effect (0.0-1.0, default: 1.0)

6. Simple Inpaint

Simplified interface for modifying images using natural language descriptions.

Parameters:

  • image_path (required): Path to the image file to modify
  • request (required): Natural language description of what to change in the image
  • output_filename (optional): Custom filename for the modified image

Inpainting Techniques

The inpainting functionality offers three different ways to specify what parts of an image to modify:

1. Mask-Based Inpainting

Use an existing mask image where white areas (255,255,255) indicate regions to be inpainted.

{
  "image_path": "pizza.jpg",
  "mask_path": "mask.png",
  "prompt": "Plain cheese pizza with no toppings"
}

2. Area-Based Inpainting

Specify a rectangular region to be inpainted using coordinates.

{
  "image_path": "company_banner.jpg",
  "mask_area": {
    "x": 150,
    "y": 100,
    "width": 200,
    "height": 80
  },
  "prompt": "A prominent, bold company logo"
}

3. Color-Based Inpainting

Target specific colors in the image for inpainting (great for removing elements like green basil leaves).

{
  "image_path": "pizza_with_basil.jpg",
  "target_colors": [
    [0, 128, 0],
    [34, 139, 34],
    [50, 205, 50]
  ],
  "color_tolerance": 60,
  "prompt": "Plain cheese pizza with no herbs or garnish",
  "negative_prompt": "basil, leaves, herbs, green, garnish"
}

Example Queries

Here are some example queries to try in Claude Desktop or Cursor.ai:

  • "Generate an image of a futuristic cityscape with flying cars and neon lights"
  • "Take the image from my desktop called 'portrait.jpg' and modify it to make it look like an oil painting"
  • "List all the images I've generated so far"
  • "Get a shareable URL for the image called 'sunset.jpg' in my input folder"
  • "Remove all the green basil leaves from the pizza image 'margherita.jpg'"
  • "Make the logo in 'company_banner.jpg' more visible and prominent by inpainting the logo area"
  • "Remove the person wearing a red shirt from the group photo 'team.jpg'"
  • "Use simple_inpaint to remove the clouds from 'landscape.jpg' and make it a clear sunny day"
  • "Use simple_inpaint to fix the blurry text in 'document.jpg' and make it sharp and readable"

Best Practices for Inpainting

For best results with the inpainting tool:

  1. Be specific in prompts: Describe exactly what should replace the masked area
  2. Use negative prompts: Explicitly state what should NOT appear in the inpainted area
  3. Adjust color tolerance: For color-based targeting, increase tolerance to capture more shades
  4. Multiple steps for complex tasks: For challenging modifications, break it down into multiple inpainting operations
  5. Choose the right targeting method:
    • For colored elements (like basil): Use color-based targeting
    • For specific regions (like logos): Use area-based targeting
    • For complex shapes: Create a custom mask image

Example Scripts

The project includes example scripts demonstrating different use cases:

Removing Basil Leaves

npm run remove-basil

This example demonstrates how to use color-based targeting to remove green basil leaves from a pizza image.

Enhancing Logo and Flattening Crust

npm run enhance-logo

This example shows a multi-step process: first enhancing a logo using area-based targeting, then flattening the crust edges around a pizza.

Development

# Run in development mode with hot reloading
npm run dev

# Build for production
npm run build

# Start the server
npm start

# Run the basil removal example
npm run remove-basil

# Run the logo enhancement example
npm run enhance-logo

# Run the simplified inpainting example
npm run simple-inpaint

Troubleshooting

Image Not Found

If you get "Image not found" errors, check:

  1. The image path is correct and accessible
  2. The image exists in one of the search directories (input, modified, generated)
  3. File permissions allow the server to access the image

API Errors

If you encounter API errors:

  1. Verify your Replicate API token and ImgBB API key are correct
  2. Check your internet connection
  3. Ensure you haven't exceeded API rate limits

Inpainting Problems

If inpainting results don't match expectations:

  1. Make your prompt more specific and detailed
  2. Add a strong negative prompt to exclude unwanted elements
  3. Adjust the color tolerance or targeting method
  4. Try breaking the task into multiple smaller inpainting operations

License

MIT