Flux Replicate 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

Related MCP server: mcp-flux-schnell

🚀 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

1. Install Dependencies

bun install

2. Configure Environment

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

3. 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:

🎨 Supported Models

Flux 2 Series (Recommended)

Flux 1 Series

🛠️ 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:

{
  "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:

{
  "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:

{
  "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

1. Open Cursor Settings → MCP section

2. Add server with command: env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y flux-replicate-mcp

3. 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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

📞 Support

• 📖 Installation Guide

• 🐛 Report Issues

• 📦 npm Package

📄 License

MIT