Replicate Flux MCP

A powerful Model Context Protocol (MCP) server that provides AI assistants with the ability to generate images using Black Forest Labs' Flux Schnell model via Replicate's API.

Installation • Features • Usage • Documentation • Contributing

🌟 Features

🖼️ High-Quality Image Generation: Access to Flux Schnell, a state-of-the-art image generation model
🤖 Seamless AI Integration: Enable AI assistants like Claude to generate images directly
🎛️ Customizable Parameters: Control aspect ratio, quality, inference steps, and more
🔌 MCP Compatible: Works with any MCP client (Cursor, Claude Desktop, Cline, Zed, etc.)
🔒 Local Processing: All requests are processed locally and securely
🔍 Prediction Management: View and retrieve your generation history

📦 Installation

NPM Global Installation

npm install -g replicate-flux-mcp

Direct Usage with NPX

REPLICATE_API_TOKEN=your_token npx -y replicate-flux-mcp

From Source

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

# Install dependencies
npm install

# Build the project
npm run build

📚 Documentation

Available Tools

`generate_image`

Generates an image based on a text prompt using the Flux Schnell model.

{
  prompt: string;                // Required: Text description of the image to generate
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  num_outputs?: number;          // Optional: Number of images to generate (1-4) (default: 1)
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
}

`prediction_list`

Retrieves a list of your recent predictions from Replicate.

{
  limit?: number;  // Optional: Maximum number of predictions to return (1-100) (default: 50)
}

`get_prediction`

Gets detailed information about a specific prediction.

{
  predictionId: string;  // Required: ID of the prediction to retrieve
}

🔧 Usage

Cursor Integration

Method 1: Using mcp.json

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

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

Replace YOUR_TOKEN with your actual Replicate API token
Restart Cursor to apply the changes

Method 2: Using Cursor MCP Settings

Open Cursor and go to Settings
Navigate to the "MCP" or "Model Context Protocol" section
Click "Add Server" or equivalent
Enter the following command in the appropriate field:

env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

Replace YOUR_TOKEN with your actual Replicate API token
Save the settings and restart Cursor if necessary

Claude Desktop Integration

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

Smithery Integration

This MCP server is available as a hosted service on Smithery, allowing you to use it without setting up your own server.

Visit Smithery and create an account if you don't have one
Navigate to the Replicate Flux MCP server page
Click "Add to Workspace" to add the server to your Smithery workspace
Configure your MCP client (Cursor, Claude Desktop, etc.) to use your Smithery workspace URL

Benefits of using the Smithery-hosted version:

No local setup required
Always running the latest version
Managed infrastructure and reliability
Easy integration with other Smithery MCP servers

For more information on using Smithery with your MCP clients, visit the Smithery documentation.

💻 Local Development

Clone the repository:

git clone https://github.com/yourusername/replicate-flux-mcp.git
cd replicate-flux-mcp

Install dependencies:

npm install

Start development mode:

npm run dev

Build the project:

npm run build

🛠 Technical Stack

Model Context Protocol SDK - Core MCP functionality
Replicate API - Image generation service
TypeScript - Type safety and modern JavaScript features
Zod - Runtime type validation

⚙️ Configuration

The server can be configured by modifying the CONFIG object in src/index.ts:

const CONFIG = {
  serverName: "replicate-flux-mcp",
  serverVersion: "0.0.1",
  modelId: "black-forest-labs/flux-schnell",
  pollingAttempts: 5,
  pollingInterval: 2000, // ms
};

🔍 Troubleshooting

Common Issues

Authentication Error

Ensure your REPLICATE_API_TOKEN is correctly set in the environment
Verify your token is valid by testing it with the Replicate API directly

Timeout Error

The server polls for completion 5 times by default
For larger images or busy servers, try increasing pollingAttempts or pollingInterval

Safety Filter Triggered

The model has a built-in safety filter that may block certain prompts
Try modifying your prompt to avoid potentially problematic content

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🔗 Resources

Made with ❤️ by Yaroslav Boiko

replicate-flux-mcp

Integrations