FLUX Image Generator — MCP Tool for Claude

Generate images directly inside Claude using FLUX.1-schnell — one of the best open-source image models available today.

Claude doesn't generate images natively. This tool bridges that gap: install it once and Claude will be able to create images on demand from any conversation.

How it works

This is an MCP server (Model Context Protocol — Anthropic's open standard for extending Claude with external tools). Once installed, Claude detects image requests automatically and calls this server in the background. You just talk to Claude normally.

You: "Generate a photo of a futuristic city at night, 16:9"
Claude: [calls generate_image tool] → shows the image inline + saves it locally

Prerequisites

Python 3.10+ — check with python3 --version
Claude Desktop or Claude Code CLI (both free)
HuggingFace account (free) — to get your API token

Installation

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/flux-image-generator.git
cd flux-image-generator

2. Create a virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Get your HuggingFace token

Create a free account at huggingface.co
Go to huggingface.co/settings/tokens
Click New token → select Read access → copy it

Important: FLUX.1-schnell is a gated model. Before your token works you need to visit huggingface.co/black-forest-labs/FLUX.1-schnell and accept the license while logged in.

4. Set your token and connect to Claude

Choose the client you use:

Option A — Claude Code CLI (recommended)

The repo includes a .mcp.json file, so Claude Code picks up the tool automatically when you open the project folder. You just need to export your token:

export HF_TOKEN=hf_your_token_here   # add this to ~/.zshrc or ~/.bashrc to make it permanent

Then open Claude Code from inside the repo folder:

cd flux-image-generator
claude

The tool will be available immediately. No extra configuration needed.

Want to use it from any folder? Register it globally with:

claude mcp add flux-image-generator -s user \
  -- /absolute/path/to/flux-image-generator/venv/bin/python \
     /absolute/path/to/flux-image-generator/server.py

This saves it to ~/.claude/settings.json so it's available in every project. Verify with claude mcp list.

Option B — Claude Desktop

Open Claude Desktop's config file:

| OS | Path | |---------|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Add the following block (replace the paths and token with your own):

{
  "mcpServers": {
    "flux-image-generator": {
      "command": "/absolute/path/to/flux-image-generator/venv/bin/python",
      "args": ["/absolute/path/to/flux-image-generator/server.py"],
      "env": {
        "HF_TOKEN": "hf_your_token_here"
      }
    }
  }
}

macOS example (replace yourname with your username):

{
  "mcpServers": {
    "flux-image-generator": {
      "command": "/Users/yourname/flux-image-generator/venv/bin/python",
      "args": ["/Users/yourname/flux-image-generator/server.py"],
      "env": {
        "HF_TOKEN": "hf_your_token_here"
      }
    }
  }
}

Fully quit and reopen Claude Desktop. You should see a hammer icon (🔨) in the chat input — that means the tool is connected.

Usage

Just ask Claude naturally:

"Generate an image of an astronaut riding a horse on Mars"
"Create a 16:9 wallpaper of a Japanese temple in autumn"
"Draw a minimalist logo for a coffee shop"
"Make a portrait photo of a golden retriever puppy, 3:4"

Available aspect ratios

| Option | Resolution | Best for | |--------|-------------|---------------------------------| | 1:1 | 1024 × 1024 | General use, social media posts | | 16:9 | 1360 × 768 | Wallpapers, YouTube thumbnails | | 9:16 | 768 × 1360 | Phone wallpapers, Stories | | 4:3 | 1024 × 768 | Presentations, classic photos | | 3:4 | 768 × 1024 | Portraits, book covers |

Generated images are automatically saved to ~/generated_images/.

Troubleshooting

The tool doesn't appear in Claude Code

Make sure you're running claude from inside the repo folder (where .mcp.json lives)
Verify HF_TOKEN is exported in your shell: echo $HF_TOKEN

The hammer icon doesn't appear in Claude Desktop

Make sure you fully quit and relaunched Claude Desktop
Verify the paths in your config file are absolute (not relative)
Check for JSON syntax errors in the config file

Error: HF_TOKEN is not set

Claude Code: run export HF_TOKEN=hf_... in your terminal before launching claude
Claude Desktop: make sure the token is in the "env" block of your config

Error 403 from HuggingFace

You need to accept the model license at huggingface.co/black-forest-labs/FLUX.1-schnell

Image generation is slow

FLUX.1-schnell typically takes 10–30 seconds via the free inference API. This is normal.

Also works as a standalone CLI

If you prefer to use it without Claude:

./run.sh "a mountain at sunrise" --output photo.png --size 16:9

License

MIT — free to use, modify, and share.

Built with FLUX.1-schnell by Black Forest Labs and MCP by Anthropic.

MCP Servers