Flux Replicate MCP Server

!Generated with Flux 2 Pro via this MCP server

A simple Model Context Protocol (MCP) server for generating images using Flux models via the Replicate API.

✨ Simplicity First

This server has been designed with simplicity as the primary goal:

Minimal setup - Just add your API key and start generating images
Zero configuration - Works out of the box with sensible defaults
Platform-aware - Automatically organizes your images in the right place
Essential features only - Image generation that just works, without complexity
Easy integration - Drop into any MCP client with a single command

🚀 Quick Start

Global Installation (Recommended)

The easiest way to get started is with npx or bunx - no installation required!

# Set your Replicate API token
export REPLICATE_API_TOKEN="r8_your_token_here"

# Run with npx (Node.js)
npx flux-replicate-mcp

# OR run with bunx (Bun)
bunx flux-replicate-mcp

CLI Arguments

The server supports comprehensive CLI configuration:

# Basic usage with API key
flux-replicate-mcp --api-key r8_your_token_here

# Full configuration example
flux-replicate-mcp \
  --api-key r8_your_token_here \
  --model flux-1.1-pro \
  --format jpg \
  --quality 95 \
  --working-directory ~/MyImages

# Get help
flux-replicate-mcp --help

Available CLI Arguments:

--api-key/-k/--replicate-api-key: Replicate API token (required)
--model/-m: Default model (flux-2-pro, flux-2-max, flux-2-flex, flux-2-dev, flux-2-klein, flux-1.1-pro, flux-pro, flux-schnell, flux-ultra)
--format/-f: Output format (jpg, png, webp)
--quality/-q: Quality setting (1-100)
--working-directory/-d/--dir: Custom working directory
--help/-h: Show help message

📖 Complete Installation Guide →

Local Development

Install Dependencies

bun install

Configure Environment

cp .env.example .env
# Edit .env and add your REPLICATE_API_TOKEN

Build and Run

bun run build
bun run start

The server will automatically create a platform-specific working directory for your generated images:

Windows: %USERPROFILE%\Documents\FluxImages
macOS: ~/Pictures/FluxImages
Linux: ~/Pictures/FluxImages (fallback: ~/flux-images)

🔧 Configuration

All configuration is done via environment variables or CLI arguments:

| Variable | CLI Argument | Required | Default | Description | |----------|--------------|----------|---------|-------------| | REPLICATE_API_TOKEN | --api-key | ✅ | - | Your Replicate API token | | FLUX_DEFAULT_MODEL | --model | ❌ | flux-2-pro | Default model | | FLUX_OUTPUT_FORMAT | --format | ❌ | jpg | Default output format | | FLUX_OUTPUT_QUALITY | --quality | ❌ | 80 | Default quality for lossy formats (1-100) | | FLUX_WORKING_DIRECTORY | --working-directory | ❌ | Platform-specific | Custom working directory |

🎨 Supported Models

Flux 2 Series (Recommended)

| Model | Cost per Image | Speed | Quality | Best For | |-------|----------------|-------|---------|----------| | flux-2-pro | $0.030 | Medium | Highest | Professional work, detailed images (default) | | flux-2-max | $0.080 | Slow | Ultra High | Premium quality, final outputs | | flux-2-flex | $0.060 | Medium | High | Flexible, general purpose | | flux-2-dev | $0.012 | Fast | Good | Development, experimentation | | flux-2-klein | $0.003 | Fast | Good | Quick iterations, budget-friendly |

Flux 1 Series

| Model | Cost per Image | Speed | Quality | Best For | |-------|----------------|-------|---------|----------| | flux-1.1-pro | $0.040 | Medium | Highest | Professional work, detailed images | | flux-pro | $0.040 | Medium | High | General purpose, balanced quality | | flux-schnell | $0.003 | Fast | Good | Quick iterations, testing | | flux-ultra | $0.060 | Slow | Ultra High | Premium quality, final outputs |

🛠️ Available Tools

`generate_image`

Generate images using Flux models with cost tracking.

Parameters:

prompt (required): Text description of the image to generate
output_path (optional): Absolute file path for the generated image. If not provided, auto-generated filename will be used in server working directory.
model (optional): Flux model to use (default: flux-2-pro)
width (optional): Image width in pixels (default: 1024)
height (optional): Image height in pixels (default: 768)
quality (optional): Image quality for lossy formats (1-100, default: 80)

Examples:

Auto-generated filename with cost tracking: ``json { "prompt": "A serene mountain landscape at sunset" } `` Response includes: file path, generation time, model used, and cost ($0.040 for flux-1.1-pro)

Custom absolute path: ``json { "prompt": "Professional product photo of a smartphone", "output_path": "/absolute/path/to/smartphone.png", "model": "flux-pro", "width": 1024, "height": 1024, "quality": 95 } ``

Fast iteration with flux-schnell: ``json { "prompt": "Quick concept art of a robot", "model": "flux-schnell", "output_path": "/home/user/images/robot_concept.jpg" } `` Only $0.003 per image - perfect for rapid prototyping

Output Organization:

Auto-generated: Files saved with descriptive names based on prompt and timestamp in server working directory
Custom path: output_path must be an absolute path for the generated image
Path validation: Relative paths are rejected to ensure compatibility across client/server environments
Directory creation: Output directories are automatically created if they don't exist
Cost tracking: Every generation shows the cost and model used

🎯 Design Philosophy

This server follows the principle: "Simple enough to understand in 30 minutes, powerful enough to generate great images"

What's Included

✅ Core image generation with Core Flux models
✅ Image processing and format conversion
✅ Platform-specific working directories
✅ CLI argument support with comprehensive help
✅ Cost tracking for budget awareness
✅ Basic error handling and logging
✅ MCP protocol compliance

🔗 MCP Integration

Claude Desktop (Recommended)

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "flux-replicate": {
      "command": "npx",
      "args": ["flux-replicate-mcp"],
      "env": {
        "REPLICATE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor Integration

Method 1: Using mcp.json

Create or edit .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "flux-replicate": {
      "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
      "args": ["-y", "flux-replicate-mcp"]
    }
  }
}

Method 2: Manual Configuration

Open Cursor Settings → MCP section
Add server with command: env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y flux-replicate-mcp
Restart Cursor

Other MCP Clients

The server works with any MCP-compatible client:

Cline: Use the same npx command
Zed: Add to MCP configuration
Custom clients: Use the MCP SDK

📖 Complete Integration Guide →

🚨 Error Handling

The server uses simple error codes with helpful messages:

AUTH: Authentication/API key issues
API: Replicate API errors
VALIDATION: Invalid input parameters
PROCESSING: Image processing failures

All errors are logged as structured JSON to stderr for MCP compatibility.

💰 Cost Management

Track your spending with built-in cost reporting:

Each generation shows the exact cost
Model pricing clearly displayed
Choose models based on budget vs quality needs
Use flux-2-klein for cheap iterations ($0.003)
Use flux-2-max for premium results ($0.080)

📦 Installation & Usage

Global Installation

# Install globally
npm install -g flux-replicate-mcp

# Or use directly with npx
npx flux-replicate-mcp --api-key YOUR_TOKEN

# Or use with bunx
bunx flux-replicate-mcp --api-key YOUR_TOKEN

Package Information

Package Name: flux-replicate-mcp
Binaries: flux-replicate-mcp, flux-replicate-mcp-server
Dependencies: 3 runtime dependencies
Size: ~600KB unpacked

📝 Development

Build

bun run build

Development Mode

bun run dev

Publish to npm

# Build and publish
bun run build
npm publish

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📞 Support

📄 License

MIT

flux-replicate-mcp