Flux MCP Server
The Flux MCP Server gives AI agents focused access to RunAPI's Flux image-generation models through a set of MCP tools. Here's what you can do:
login— Authenticate via a browser-based PKCE flow, saving the API key to~/.config/runapi/config.json. Supports aforceflag to re-run login. Auth also resolves from theRUNAPI_API_KEYenv var for headless/CI use.text_to_image— Create a Flux text-to-image task usingflux-2-klein,flux-dev, orflux-pro. Configurewait,timeout_ms,poll_interval_ms,aspect_ratio,output_count, andcallback_url. Returns task ID, status, and output URLs.remix_image— Create a Flux remix-image task from a source image URL + prompt usingflux-devorflux-pro, with the same configurable options as text-to-image.get_task— Fetch the current status and latest result payload for an existing task by providing the task ID and endpoint/action type.check_pricing— Look up current pricing for any Flux model and endpoint — works without authentication.
The server works with Claude Code, Codex, Cursor, Windsurf, VS Code, Roo Code, and any MCP-compatible host via stdio.
Provides tools for generating images via RunAPI's Flux model line, including text-to-image and remix image operations, task status polling, and pricing lookup.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Flux MCP ServerGenerate a photorealistic image of a cat in a spacesuit using flux-pro"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Why This Package?
@runapi.ai/flux-mcp is a focused Model Context Protocol server for the Flux model line on RunAPI.
It gives MCP-compatible assistants direct access to 2 endpoints and 3 model variants without loading the full RunAPI catalog.
Use this per-model server when an agent should stay scoped to Flux. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.
Related MCP server: NIMGEN
Install
Add it to Claude Code:
claude mcp add flux -s user -- npx -y @runapi.ai/flux-mcpUse project scope when the server should be shared with a repository:
claude mcp add flux -s project -- npx -y @runapi.ai/flux-mcpCodex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:
{
"mcpServers": {
"flux": {
"command": "npx",
"args": ["-y", "@runapi.ai/flux-mcp"]
}
}
}check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login.
Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.
Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.
Tools
Tool | Auth | Purpose |
| Yes | Create a Flux remix image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Flux text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Fetch the current status and latest payload for an existing task. |
| No | Look up current pricing for a Flux model and endpoint. |
Models
Flux covers 3 model variants across 2 endpoints. Each tool accepts the models listed for it:
Tool | Models |
|
|
|
|
Model availability can change between releases. Use check_pricing or the Flux model page for the current catalog view.
Agent Prompts
Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.
Create a task
Run a Flux remix image task with RunAPI.The assistant can call check_pricing, then remix_image, and return the task id, status, and output URLs.
Submit without waiting
Create the task but don't wait for it to finish.The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.
Check pricing before creating
Check current Flux pricing, then create the task if it matches my request.The assistant calls check_pricing and can link to the Flux model page for the canonical catalog entry.
Configuration
The server resolves auth in this order:
RUNAPI_API_KEYenvironment variable, useful for headless and CI hosts~/.config/runapi/config.json, created by the MCPlogintool orrunapi loginNo key, which still allows
check_pricing
The config file is normally managed by login. A pre-provisioned headless config can use:
{
"apiKey": "your_runapi_key"
}Do not commit real API keys.
Links
Resource | URL |
Flux model page | |
npm package | |
GitHub repository | |
RunAPI MCP overview | |
RunAPI docs |
License
Licensed under the Apache License, Version 2.0.
Available Tools
5 toolscheck_pricingB
Look up RunAPI pricing for the flux model line.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model slug. Defaults to the line's primary model. | |
| action | No | Endpoint name. Defaults to the endpoint that offers the model. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. "Look up" strongly implies a read-only, side-effect-free query, which is adequate for a simple pricing fetch, but it never explicitly states that nothing is mutated, whether auth or credits are required, or whether results are cached. Adding one clause about the read-only nature and output scope would close the gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb and scope leading, and no filler. It is efficiently sized, though it is on the thin side for a tool with two optional, default-bearing parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with full schema coverage and no output schema, the description is minimally sufficient but does not explain what the returned pricing data looks like or how the model/action defaults interact with the "flux model line" framing. An agent could still call it correctly, but the context is thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (model, action) are already documented in the schema, including their defaults and the action enum. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ("look up") and resource ("pricing for the flux model line"), so the agent knows exactly what this returns. It does not need sibling differentiation because no sibling (get_task, login, remix_image, text_to_image) performs pricing work. The only friction is that it scopes to the flux line while the schema implies a general model string.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no stated preconditions, and no mention of alternatives or how it relates to the action endpoints (remix_image, text_to_image) it prices. The agent must infer that this is a pre-flight cost check rather than something routed from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_taskA
Fetch the current status and latest result payload for a flux task.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Asynchronous endpoint the task was created on. | |
| task_id | Yes | Task id returned when the task was created. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a read operation ('Fetch') and what is returned ('status and latest result payload'), but it omits auth requirements, rate limits, error behavior, and whether the returned payload can be large or paginated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It efficiently communicates the core purpose and return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with full schema coverage and no output schema, the description is largely complete. It states the purpose and the kind of result returned, though it could better connect to task-creation siblings and polling behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (task_id and action) are documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Fetch') and resource ('flux task'), and describes what is returned ('current status and latest result payload'). It clearly distinguishes the tool from sibling creation endpoints like remix_image and text_to_image, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (checking the status of an async task) but gives no explicit when-to-use, when-not-to-use, or alternatives. There is no mention of polling after task creation or of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
loginA
Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Re-run browser login when the current credential comes from the local config file. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the interactive browser flow and the file write side effect (config.json). However, it does not mention that it may overwrite existing credentials or that it could block waiting for user input, though these are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action ('Authenticate RunAPI') and provides necessary details without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple login tool with one optional parameter and no output schema, the description covers the core purpose and side effect. It lacks an explicit statement that this is a prerequisite for other tools, but that is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the only parameter 'force' has a description). The tool description adds no additional meaning about parameters beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Authenticate'), target resource ('RunAPI'), method ('browser PKCE login flow'), and side effect (saving to config.json). It is distinct from sibling tools, none of which relate to authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to authenticate RunAPI) but does not explicitly say when to run it (e.g., before other RunAPI tools) or when to use the 'force' parameter. Since there are no alternative auth tools among siblings, 'vs alternatives' is not applicable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remix_imageB
Create a Flux task on RunAPI (remix image). Returns a task id, status, and output URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Poll until the task reaches a terminal status. | |
| model | No | RunAPI model slug for this model line. | |
| prompt | Yes | Declared type: string. | |
| timeout_ms | No | ||
| aspect_ratio | No | Declared type: string. Known values: "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3". | |
| callback_url | No | Declared type: string. | |
| output_count | No | Declared type: integer. Known values: 1. | |
| poll_interval_ms | No | ||
| source_image_url | Yes | Declared type: string. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It mentions the return shape (task id, status, output URLs), which is useful, but says nothing about async/polling semantics, the meaning of the 'wait' flag, callback behavior, auth requirements, or side effects of creating a remote task.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the action is front-loaded and the return-value note earns its place given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter async task-creation tool with no annotations, the description is thin: it omits the create-then-poll workflow, the role of the sibling get_task, and any failure/timeout behavior. The mention of returned task id/status/output URLs partially compensates for the absent output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 78%, so the schema already documents most parameters (wait, model, aspect_ratio, output_count, etc.). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a Flux task on RunAPI (remix image)') and names the model line, which helps distinguish it from the sibling text_to_image. The parenthetical 'remix image' is somewhat terse about what remixing means, but the core action is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus text_to_image, nor any mention of the relationship with get_task for retrieving results. The agent must infer the usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
text_to_imageB
Create a Flux task on RunAPI (text to image). Returns a task id, status, and output URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Poll until the task reaches a terminal status. | |
| model | No | RunAPI model slug for this model line. | |
| prompt | Yes | Declared type: string. | |
| timeout_ms | No | ||
| aspect_ratio | No | Declared type: string. Known values: "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3". | |
| callback_url | No | Declared type: string. | |
| output_count | No | Declared type: integer. Known values: 1. | |
| poll_interval_ms | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It does disclose the async task-based nature and the return shape (task id, status, output URLs), which is meaningful. But it omits auth requirements, cost implications, and how the 'wait' polling behavior affects the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and followed by the return values. Efficient with no wasted text, though extremely terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must compensate; it partially does by naming return fields. However, with 8 parameters and an async task lifecycle, it should explain at least the wait/polling semantics and how to retrieve results afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, near the high-coverage baseline, so the schema does most of the work. The description adds nothing about the 8 parameters (prompt, model, aspect_ratio, callback_url, timeout_ms, poll_interval_ms, output_count, wait) beyond the text-to-image framing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('Flux task') plus a clarifying parenthetical ('text to image'). It is distinguishable from get_task and remix_image by name and scope, but it does not explicitly contrast with the sibling remix_image, which also involves image generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus remix_image or get_task, and no prerequisites or context about the RunAPI task workflow. The agent must infer the use case from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.2.0- Changed
check_pricing2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - removed
Input schema / properties / model / enumRemoved value: -[ - "flux-dev", - "flux-pro", - "flux-2-klein" -]
- Changed
get_task1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
remix_image14 fields changed- changed
Input schema / additionalPropertiesPrevious value: -falseNew value: +{} - added
Input schema / properties / aspect_ratio / descriptionAdded value: +"Declared type: string. Known values: \"1:1\", \"4:3\", \"3:4\", \"16:9\", \"9:16\", \"3:2\", \"2:3\"." - removed
Input schema / properties / aspect_ratio / enumRemoved value: -[ - "1:1", - "4:3", - "3:4", - "16:9", - "9:16", - "3:2", - "2:3" -] - added
Input schema / properties / callback_url / descriptionAdded value: +"Declared type: string." - removed
Input schema / properties / model / enumRemoved value: -[ - "flux-dev", - "flux-pro" -] - added
Input schema / properties / output_count / descriptionAdded value: +"Declared type: integer. Known values: 1." - removed
Input schema / properties / output_count / enumRemoved value: -[ - 1 -] - changed
Input schema / properties / output_count / typePrevious value: -"number"New value: +"integer" - added
Input schema / properties / poll_interval_ms / maximumAdded value: +9007199254740991 - added
Input schema / properties / prompt / descriptionAdded value: +"Declared type: string." - removed
Input schema / properties / prompt / maxLengthRemoved value: -5000 - removed
Input schema / properties / prompt / minLengthRemoved value: -3 - added
Input schema / properties / source_image_url / descriptionAdded value: +"Declared type: string." - added
Input schema / properties / timeout_ms / maximumAdded value: +9007199254740991
- Changed
text_to_image13 fields changed- changed
Input schema / additionalPropertiesPrevious value: -falseNew value: +{} - added
Input schema / properties / aspect_ratio / descriptionAdded value: +"Declared type: string. Known values: \"1:1\", \"4:3\", \"3:4\", \"16:9\", \"9:16\", \"3:2\", \"2:3\"." - removed
Input schema / properties / aspect_ratio / enumRemoved value: -[ - "1:1", - "4:3", - "3:4", - "16:9", - "9:16", - "3:2", - "2:3" -] - added
Input schema / properties / callback_url / descriptionAdded value: +"Declared type: string." - removed
Input schema / properties / model / enumRemoved value: -[ - "flux-2-klein", - "flux-dev", - "flux-pro" -] - added
Input schema / properties / output_count / descriptionAdded value: +"Declared type: integer. Known values: 1." - removed
Input schema / properties / output_count / enumRemoved value: -[ - 1 -] - changed
Input schema / properties / output_count / typePrevious value: -"number"New value: +"integer" - added
Input schema / properties / poll_interval_ms / maximumAdded value: +9007199254740991 - added
Input schema / properties / prompt / descriptionAdded value: +"Declared type: string." - removed
Input schema / properties / prompt / maxLengthRemoved value: -5000 - removed
Input schema / properties / prompt / minLengthRemoved value: -3 - added
Input schema / properties / timeout_ms / maximumAdded value: +9007199254740991
5 tool updates
v0.1.0- First observed
check_pricing - First observed
get_task - First observed
login - First observed
remix_image - First observed
text_to_image
TDQS
Scored across 5 tools
Each tool targets a distinct action: authenticate (login), create a task (remix_image, text_to_image), poll a task (get_task), and look up cost (check_pricing). The two creation tools overlap in returning a task id but are clearly separated by input modality, so misselection is unlikely.
All names use snake_case, and most follow a verb_noun pattern (get_task, remix_image, check_pricing). The lone bare verb (login) and the noun-style text_to_image are minor deviations that don't hurt readability.
Five tools is a lean but reasonable surface for a single-purpose image-generation API: auth, two generation modes, task polling, and pricing. It is slightly thin, with no list or cancel operations, but nothing feels redundant.
The core workflow is covered end-to-end: authenticate, submit a task, poll its status/result, and check pricing. Minor gaps exist (no task listing, cancellation, or delete), but agents can work around these by tracking task ids themselves.
Maintenance
Related MCP Connectors
MCP server for Flux AI image generation
Official FLUX MCP server. Generate, edit, vary, and browse images from Black Forest Labs.
Generate AI images and videos from any compatible MCP client.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn MCP server that enables AI assistants to generate images using Black Forest Labs API and FLUX models, with automatic polling and image URL retrieval.11 npm1MIT
- AlicenseAqualityCmaintenanceFirst MCP server for NVIDIA NIM FLUX. Generate and edit images using FLUX.1 models with your existing NVIDIA API key.3572 npmApache 2.0
- AlicenseAqualityAmaintenanceMCP server for the Flux Kontext model line that enables text-to-image generation, task status polling, and pricing lookup via RunAPI.468 npmApache 2.0

@runapi.ai/flux-2-mcpofficial
AlicenseBqualityBmaintenanceRunAPI MCP server for the Flux 2 model line. Create tasks, poll their status, and check pricing through a single RunAPI API key.553 npmApache 2.0