home / mcp / flux mcp server

Flux MCP Server

Exposes FLUX image generation models to Claude Desktop/Code and MCP clients via a local MCP server.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "kmaurinjones-flux-mcp": {
      "command": "npx",
      "args": [
        "flux-mcp@latest"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

You can expose Replicate’s FLUX image generation models to Claude Desktop, Claude Code, and other MCP clients by running a lightweight MCP server. This setup lets you generate high-quality images from prompts, variations, and inpainting workflows while keeping your API token secure and centrally managed.

How to use

Use the MCP server by launching it as a local service that Claude or other MCP clients can connect to. You have two practical startup methods: a local CLI approach using npx or node, or a direct node script run for development. Once the server is running, you can list available FLUX models and generate images through your MCP client’s interface, using the configured environment variable to authenticate with Replicate.

How to install

Prerequisites: ensure you have Node.js 18+ installed and a Replicate API token.

Install the Flux MCP server globally from source or publish-ready package, then start the server with your token.

Configuring the MCP server for Claude clients

There are explicit MCP configuration snippets you can reuse. The server is exposed to Claude Code and Claude Desktop through standard MCP commands that launch the Flux MCP server process and pass the Replicate API token.

# From local directory
cd /path/to/flux-mcp-node
claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- node /absolute/path/to/flux-mcp-node/index.js

# From npm after publishing
claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- npx flux-mcp@latest

Claude Desktop and Claude Code integration

For Claude Desktop, add an MCP server entry that runs the package via npx and passes your Replicate API token. For local development, you can run the server with node and the absolute path to the index file.

{
  "mcpServers": {
    "flux-mcp": {
      "command": "npx",
      "args": ["flux-mcp@latest"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "flux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/flux-mcp-node/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

Starting the server locally

To start a local development server, run the node script with your token. This keeps a minimal local workflow that you can test before publishing to MCP.

# Local development start example
export REPLICATE_API_TOKEN="r8_..."
node index.js

Notes on running with Claude Studio tools

The server provides two tools to interact with the Flux models: flux_models to list available models with usage notes, and flux_generate to generate images and return file paths and URLs.

Additional configuration and security

Security considerations include validating download paths, restricting URL sources to HTTPS and the replicate.delivery domain, sanitizing inputs, and handling errors securely. The MCP server enforces these safeguards to prevent common attack vectors while providing reliable access to the FLUX models.

Troubleshooting

If you encounter issues, ensure your environment variable is set, verify the server process is running, and check that your download paths are writable. If a model requires an input image, provide image_path accordingly.

Development

For development, you can clone the project, install dependencies, and run the server locally. This enables you to test MCP integration and model usage before deploying.

Available tools

flux_models

List available Flux models with usage notes to understand capabilities and inputs.

flux_generate

Generate images, save to local disk, and return file paths and public URLs.