Skip to content
Back to search

replicate-flux-mcp

MCP for Replicate Flux Model - A powerful tool for generating customized images and SVG assets that match specific coding vibes and aesthetic styles. Streamline your visual asset creation process with AI-powered design generation tailored for developers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/awkoy--replicate-flux-mcp/badge.svg)](/listings/awkoy--replicate-flux-mcp)

HTML

<a href="/listings/awkoy--replicate-flux-mcp"><img src="/api/listings/awkoy--replicate-flux-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Setup Process

1. **Obtain a Replicate API Token** - Sign up at [Replicate](https://replicate.com/) - Create an API token in your account settings

2. **Choose Your Integration Method** - Follow one of the integration options below based on your preferred MCP client

3. **Ask Your AI Assistant to Generate an Image** - Simply ask naturally: "Can you generate an image of a serene mountain landscape at sunset?" - Or be more specific: "Please create an image showing a peaceful mountain scene with a lake reflecting the sunset colors in the foreground"

4. **Explore Advanced Features** - Try different parameter settings for customized results - Experiment with SVG generation using `generate_svg` - Use batch image generation or variant generation features

Cursor Integration

Method 1: Using mcp.json

1. 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"]
    }
  }
}

2. Replace `YOUR_TOKEN` with your actual Replicate API token 3. Restart Cursor to apply the changes

Method 2: Manual Mode

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

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

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

Claude Desktop Integration

1. Create or edit the `mcp.json` file in your configuration directory:

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

2. Replace `YOUR_TOKEN` with your actual Replicate API token 3. Restart Claude Desktop to apply the changes

Smithery Integration

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

1. Visit [Smithery](https://smithery.ai/) and create an account if you don't have one 2. Navigate to the [Replicate Flux MCP server page](https://smithery.ai/server/@awkoy/replicate-flux-mcp) 3. Click "Add to Workspace" to add the server to your Smithery workspace 4. Configure your MCP client (Cursor, Claude Desktop, etc.) to use your Smithery workspace URL

For more information on using Smithery with your MCP clients, visit the [Smithery documentation](https://smithery.ai/docs).

Glama.ai Integration

This MCP server is also available as a hosted service on Glama.ai, providing another option to use it without local setup.

1. Visit [Glama.ai](https://glama.ai/) and create an account if you don't have one 2. Go to the [Replicate Flux MCP server page](https://glama.ai/mcp/servers/ss8n1knen8) 3. Click "Install Server" to add the server to your workspace 4. Configure your MCP client to use your Glama.ai workspace

For more information, visit the [Glama.ai MCP servers documentation](https://glama.ai/mcp/servers).

Codex Integration

Add the server to `~/.codex/config.toml`:

[mcp_servers.replicate]
command = "npx"
args = ["-y", "replicate-flux-mcp"]
env = { REPLICATE_API_TOKEN = "your-replicate-api-token", REPLICATE_IMAGE_MODEL_ID = "your-image-model-id", REPLICATE_SVG_MODEL_ID = "your-svg-model-id" }
startup_timeout_sec = 30_000

Replace the env values as needed. If you omit `REPLICATE_IMAGE_MODEL_ID` / `REPLICATE_SVG_MODEL_ID`, the server uses `black-forest-labs/flux-schnell` for images and `recraft-ai/recraft-v3-svg` for SVGs.

Curated tools validate model overrides against built-in allowlists:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 566 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/awkoy-replicate-flux-mcp-badge.png)](https://mseep.ai/app/awkoy-replicate-flux-mcp)
  2. # Replicate Flux MCP
  3. [English](README.md) | [中文](README.zh.md)
  4. ![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)
  5. ![License](https://img.shields.io/badge/license-MIT-green)
  6. ![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue)
  7. ![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-purple)
  8. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/awkoy/replicate-flux-mcp)](https://archestra.ai/mcp-catalog/awkoy__replicate-flux-mcp)
  9. [![LightNow](https://lightnow.ai/badge/io.github.awkoy/replicate-flux-mcp)](https://lightnow.ai/servers/io.github.awkoy/replicate-flux-mcp)
  10. ![NPM Downloads](https://img.shields.io/npm/dw/replicate-flux-mcp)
  11. ![Stars](https://img.shields.io/github/stars/awkoy/replicate-flux-mcp)
  12. <a href="https://glama.ai/mcp/servers/ss8n1knen8">
  13. <img width="380" height="200" src="https://glama.ai/mcp/servers/ss8n1knen8/badge" />
  14. </a>
  15. **Replicate Flux MCP** is an advanced Model Context Protocol (MCP) server that empowers AI assistants to generate high-quality images and vector graphics. By default it uses [black-forest-labs/flux-schnell](https://replicate.com/black-forest-labs/flux-schnell) for raster images and [recraft-ai/recraft-v3-svg](https://replicate.com/recraft-ai/recraft-v3-svg) for SVG output. You can override the curated image/SVG models through environment variables, and image tools also accept a per-call `model_id` override from the built-in allowlist.
  16. ## 📑 Table of Contents
  17. - [Getting Started & Integration](#-getting-started--integration)
  18. - [Setup Process](#setup-process)
  19. - [Cursor Integration](#cursor-integration)
  20. - [Claude Desktop Integration](#claude-desktop-integration)
  21. - [Smithery Integration](#smithery-integration)
  22. - [Glama.ai Integration](#glamaai-integration)
  23. - [Codex Integration](#codex-integration)
  24. - [Features](#-features)
  25. - [Documentation](#-documentation)
  26. - [Available Tools](#available-tools)
  27. - [Available Resources](#available-resources)
  28. - [Available Prompts](#available-prompts)
  29. - [Structured Output](#structured-output)
  30. - [Environment Variables](#environment-variables)
  31. - [Development](#-development)
  32. - [Testing](#testing)
  33. - [Technical Details](#-technical-details)
  34. - [Troubleshooting](#-troubleshooting)
  35. - [Contributing](#-contributing)
  36. - [License](#-license)
  37. - [Resources](#-resources)
  38. - [Examples](#-examples)
  39. ## 🚀 Getting Started & Integration
  40. ### Setup Process
  41. 1. **Obtain a Replicate API Token**
  42. - Sign up at [Replicate](https://replicate.com/)
  43. - Create an API token in your account settings
  44. 2. **Choose Your Integration Method**
  45. - Follow one of the integration options below based on your preferred MCP client
  46. 3. **Ask Your AI Assistant to Generate an Image**
  47. - Simply ask naturally: "Can you generate an image of a serene mountain landscape at sunset?"
  48. - Or be more specific: "Please create an image showing a peaceful mountain scene with a lake reflecting the sunset colors in the foreground"
  49. 4. **Explore Advanced Features**
  50. - Try different parameter settings for customized results
  51. - Experiment with SVG generation using `generate_svg`
  52. - Use batch image generation or variant generation features
  53. ### Cursor Integration
  54. #### Method 1: Using mcp.json
  55. 1. Create or edit the `.cursor/mcp.json` file in your project directory:
  56. ```json
  57. {
  58. "mcpServers": {
  59. "replicate-flux-mcp": {
  60. "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
  61. "args": ["-y", "replicate-flux-mcp"]
  62. }
  63. }
  64. }
  65. ```
  66. 2. Replace `YOUR_TOKEN` with your actual Replicate API token
  67. 3. Restart Cursor to apply the changes
  68. #### Method 2: Manual Mode
  69. 1. Open Cursor and go to Settings
  70. 2. Navigate to the "MCP" or "Model Context Protocol" section
  71. 3. Click "Add Server" or equivalent
  72. 4. Enter the following command in the appropriate field:
  73. ```
  74. env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp
  75. ```
  76. 5. Replace `YOUR_TOKEN` with your actual Replicate API token
  77. 6. Save the settings and restart Cursor if necessary
  78. ### Claude Desktop Integration
  79. 1. Create or edit the `mcp.json` file in your configuration directory:
  80. ```json
  81. {
  82. "mcpServers": {
  83. "replicate-flux-mcp": {
  84. "command": "npx",
  85. "args": ["-y", "replicate-flux-mcp"],
  86. "env": {
  87. "REPLICATE_API_TOKEN": "YOUR TOKEN"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. 2. Replace `YOUR_TOKEN` with your actual Replicate API token
  94. 3. Restart Claude Desktop to apply the changes
  95. ### Smithery Integration
  96. This MCP server is available as a hosted service on Smithery, allowing you to use it without setting up your own server.
  97. 1. Visit [Smithery](https://smithery.ai/) and create an account if you don't have one
  98. 2. Navigate to the [Replicate Flux MCP server page](https://smithery.ai/server/@awkoy/replicate-flux-mcp)
  99. 3. Click "Add to Workspace" to add the server to your Smithery workspace
  100. 4. Configure your MCP client (Cursor, Claude Desktop, etc.) to use your Smithery workspace URL
  101. For more information on using Smithery with your MCP clients, visit the [Smithery documentation](https://smithery.ai/docs).
  102. ### Glama.ai Integration
  103. This MCP server is also available as a hosted service on Glama.ai, providing another option to use it without local setup.
  104. 1. Visit [Glama.ai](https://glama.ai/) and create an account if you don't have one
  105. 2. Go to the [Replicate Flux MCP server page](https://glama.ai/mcp/servers/ss8n1knen8)
  106. 3. Click "Install Server" to add the server to your workspace
  107. 4. Configure your MCP client to use your Glama.ai workspace
  108. For more information, visit the [Glama.ai MCP servers documentation](https://glama.ai/mcp/servers).
  109. ### Codex Integration
  110. Add the server to `~/.codex/config.toml`:
  111. ```toml
  112. [mcp_servers.replicate]
  113. command = "npx"
  114. args = ["-y", "replicate-flux-mcp"]
  115. env = { REPLICATE_API_TOKEN = "your-replicate-api-token", REPLICATE_IMAGE_MODEL_ID = "your-image-model-id", REPLICATE_SVG_MODEL_ID = "your-svg-model-id" }
  116. startup_timeout_sec = 30_000
  117. ```
  118. Replace the env values as needed. If you omit `REPLICATE_IMAGE_MODEL_ID` / `REPLICATE_SVG_MODEL_ID`, the server uses `black-forest-labs/flux-schnell` for images and `recraft-ai/recraft-v3-svg` for SVGs.
  119. Curated tools validate model overrides against built-in allowlists:
  120. - **Image generation**: `black-forest-labs/flux-schnell`, `google/imagen-4`, `black-forest-labs/flux-kontext-pro`, `ideogram-ai/ideogram-v3-turbo`, `black-forest-labs/flux-1.1-pro`, `black-forest-labs/flux-dev`
  121. - **SVG generation**: `recraft-ai/recraft-v3-svg`
  122. - **Legacy `run_model` extras**: `minimax/video-01`, `luma/reframe-video`, `topazlabs/video-upscale`, `topazlabs/image-upscale`, `szcho/codeformer`, `tencentarc/gfpgan`
  123. ## 🌟 Features
  124. - **🖼️ High-Quality Image Generation** — Flux Schnell raster images by default, with environment-variable and per-tool image model overrides.
  125. - **🎨 Vector Graphics** — Recraft V3 SVG for logos, icons, and diagrams.
  126. - **📊 Batch + Variants** — Generate N images from N prompts or N variants of one prompt (seed-based or prompt-modifier-based).
  127. - **🧩 Arbitrary Replicate Models** — `run_replicate_model` escape hatch accepts any `owner/name[:version]` reference, with `get_model_schema` introspection for the OpenAPI input schema. Optional allowlist via `REPLICATE_MODEL_ALLOWLIST`.
  128. - **📦 Structured Output** — Every `generate_*` tool returns machine-readable `structuredContent` alongside human-readable content, matching a per-tool `outputSchema` (URL, prompt, format, aspect ratio, per-variant seed, etc).
  129. - **⏳ Progress Notifications** — Batch and variant generation emit `notifications/progress` for clients that opt in via `progressToken`, so long runs aren't black-boxed.
  130. - **💬 Curated Prompts** — 5 ready-made prompt templates (`logo`, `portrait`, `svg-icon`, `product-shot`, `isometric-diagram`) surfaced in Claude Desktop's slash palette and Cursor's `@`-menu.
  131. - **🏷️ Proper Tool Annotations** — `readOnlyHint` / `destructiveHint` / `openWorldHint` / `idempotentHint` set correctly so clients can reason about safety and cost.
  132. - **🪵 Structured Logging** — Server-side errors travel over `notifications/message` instead of stderr.
  133. - **🔌 Universal MCP Compatibility** — MCP protocol 2025-11-25; works with Claude Desktop, Cursor, Cline, Zed, and any spec-compliant client.
  134. - **🔍 Generation History** — Browse past runs through `imagelist`, `svglist`, and `predictionlist` resources.
  135. ## 📚 Documentation
  136. ### Available Tools
  137. #### `generate_image`
  138. Generates an image based on a text prompt using the configured image model (allowlist only).
  139. ```typescript
  140. {
  141. prompt: string; // Required: Text description of the image to generate
  142. model_id?: string; // Optional: Override image model (allowlist only)
  143. seed?: number; // Optional: Random seed for reproducible generation
  144. go_fast?: boolean; // Optional: Run faster predictions with optimized model (default: true)
  145. megapixels?: "1" | "0.25"; // Optional: Image resolution (default: "1")
  146. num_outputs?: number; // Optional: Number of images to generate (1-4) (default: 1)
  147. aspect_ratio?: string; // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  148. output_format?: string; // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  149. output_quality?: number; // Optional: Image quality (0-100) (default: 80)
  150. num_inference_steps?: number; // Optional: Number of denoising steps (1-4) (default: 4)
  151. disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
    • Note: Quotes wording that overrides an agent's instructions or safety (in quotes, code, a table or an example): "disable safety filter"
    • Line 199 on GitHub
  152. support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
  153. }
  154. ```
  155. #### `generate_multiple_images`
  156. Generates multiple images based on an array of prompts using the configured image model (allowlist only).
  157. ```typescript
  158. {
  159. prompts: string[]; // Required: Array of text descriptions for images to generate (1-10 prompts)
  160. model_id?: string; // Optional: Override image model (allowlist only)
  161. seed?: number; // Optional: Random seed for reproducible generation
  162. go_fast?: boolean; // Optional: Run faster predictions with optimized model (default: true)
  163. megapixels?: "1" | "0.25"; // Optional: Image resolution (default: "1")
  164. aspect_ratio?: string; // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  165. output_format?: string; // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  166. output_quality?: number; // Optional: Image quality (0-100) (default: 80)
  167. num_inference_steps?: number; // Optional: Number of denoising steps (1-4) (default: 4)
  168. disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
    • Note: Quotes wording that overrides an agent's instructions or safety (in quotes, code, a table or an example): "disable safety filter"
    • Line 219 on GitHub
  169. support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
  170. }
  171. ```
  172. #### `generate_image_variants`
  173. Generates multiple variants of the same image from a single prompt using the configured image model (allowlist only).
  174. ```typescript
  175. {
  176. prompt: string; // Required: Text description for the image to generate variants of
  177. model_id?: string; // Optional: Override image model (allowlist only)
  178. num_variants: number; // Required: Number of image variants to generate (2-10, default: 4)
  179. prompt_variations?: string[]; // Optional: List of prompt modifiers to apply to variants (e.g., ["in watercolor style", "in oil painting style"])
  180. variation_mode?: "append" | "replace"; // Optional: How to apply variations - 'append' adds to base prompt, 'replace' uses variations directly (default: "append")
  181. seed?: number; // Optional: Base random seed. Each variant will use seed+variant_index
  182. go_fast?: boolean; // Optional: Run faster predictions with optimized model (default: true)
  183. megapixels?: "1" | "0.25"; // Optional: Image resolution (default: "1")
  184. aspect_ratio?: string; // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  185. output_format?: string; // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  186. output_quality?: number; // Optional: Image quality (0-100) (default: 80)
  187. num_inference_steps?: number; // Optional: Number of denoising steps (1-4) (default: 4)
  188. disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
    • Note: Quotes wording that overrides an agent's instructions or safety (in quotes, code, a table or an example): "disable safety filter"
    • Line 242 on GitHub
  189. support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
  190. }
  191. ```
  192. #### `generate_svg`
  193. Generates SVG/vector output based on a text prompt using the configured SVG model (allowlist only).
  194. ```typescript
  195. {
  196. prompt: string; // Required: Text description of the SVG to generate
  197. size?: string; // Optional: Size of the generated SVG (default: "1024x1024")
  198. style?: string; // Optional: Style of the generated image (default: "any")
  199. // Options: "any", "engraving", "line_art", "line_circuit", "linocut"
  200. }
  201. ```
  202. #### `prediction_list`
  203. Retrieves a list of your recent predictions from Replicate.
  204. ```typescript
  205. {
  206. limit?: number; // Optional: Maximum number of predictions to return (1-100) (default: 50)
  207. }
  208. ```
  209. #### `get_prediction`
  210. Gets detailed information about a specific prediction.
  211. ```typescript
  212. {
  213. predictionId: string; // Required: ID of the prediction to retrieve
  214. }
  215. ```
  216. #### `run_model`
  217. Runs a whitelisted Replicate model with a raw input payload (useful for video or restoration models).
  218. ```typescript
  219. {
  220. model_id: string; // Required: Replicate model id (allowlist only)
  221. input?: Record<string, unknown>; // Optional: Raw input payload for the model
  222. }
  223. ```
  224. #### `run_replicate_model`
  225. Runs any model hosted on Replicate by its `owner/name[:version]` reference. Use this as an escape hatch when none of the curated tools fit. Call `get_model_schema` first if you don't know the input shape.
  226. ```typescript
  227. {
  228. model: string; // Required: 'owner/name' or 'owner/name:version'
  229. input: Record<string, unknown>; // Required: Model input parameters
  230. prefer_wait?: number; // Optional: Seconds to block waiting for sync output (1-60, default 60)
  231. return_as?: "url" | "base64" | "both"; // Optional: How to return file outputs (default "url")
  232. }
  233. ```
  234. Set the `REPLICATE_MODEL_ALLOWLIST` env var (comma-separated `owner/name` entries) to restrict which models can be invoked. Unset = any model allowed. Set-but-empty = deny all (the server fails closed rather than silently allowing everything).
  235. #### `get_model_schema`
  236. Fetches the OpenAPI input schema and description for a Replicate model so you can pass the right parameters to `run_replicate_model`.
  237. ```typescript
  238. {
  239. model: string; // Required: Replicate model reference in 'owner/name' form
  240. }
  241. ```
  242. ### Available Resources
  243. #### `imagelist`
  244. Browse your history of generated images created with the configured image model.
  245. #### `svglist`
  246. Browse your history of generated SVG outputs created with the configured SVG model.
  247. #### `predictionlist`
  248. Browse all your Replicate predictions history.
  249. ### Available Prompts
  250. Curated templates surfaced in Claude Desktop's slash menu and Cursor's `@`-palette. Each one fills in sensible defaults then delegates to the relevant generation tool.
  251. | Prompt | Description | Arguments |
  252. | --- | --- | --- |
  253. | `logo` | Brand/product logo | `brand`, `style?`, `palette?` |
  254. | `portrait` | Photoreal portrait | `subject`, `mood?`, `lens?` |
  255. | `svg-icon` | Single-concept vector icon | `concept`, `style?` |
  256. | `product-shot` | Studio product photography | `product`, `surface?` |
  257. | `isometric-diagram` | Isometric technical illustration | `subject`, `emphasis?` |
  258. ### Structured Output
  259. Every `generate_*` tool returns both human-readable `content` (text + image blocks) and machine-readable `structuredContent` that matches the tool's `outputSchema`.
  260. | Tool | `structuredContent` shape |
  261. | --- | --- |
  262. | `generate_image` | `{ url, prompt, format, aspect_ratio, seed? }` |
  263. | `generate_svg` | `{ url, prompt, size, style, svg? }` |
  264. | `generate_multiple_images` | `{ images: [{ url, prompt }], format, aspect_ratio }` |
  265. | `generate_image_variants` | `{ base_prompt, variation_mode, variants: [{ variant_index, url, prompt_used, seed? }], format, aspect_ratio }` |
  266. Clients that understand MCP structured output can consume URLs and metadata directly without parsing prose.
  267. ### Environment Variables
  268. | Variable | Required | Purpose |
  269. | --- | --- | --- |
  270. | `REPLICATE_API_TOKEN` | yes | API token for [Replicate](https://replicate.com/account/api-tokens). The server exits immediately if it's missing. |
  271. | `REPLICATE_IMAGE_MODEL_ID` | no | Overrides the default curated image model used by `generate_image`, `generate_multiple_images`, `generate_image_variants`, and `create_prediction`. The value must be in the built-in image allowlist. |
  272. | `REPLICATE_SVG_MODEL_ID` | no | Overrides the default SVG model used by `generate_svg`. The value must be in the built-in SVG allowlist. |
  273. | `REPLICATE_MODEL_ALLOWLIST` | no | Comma-separated `owner/name` entries that gate `run_replicate_model`. **Unset** = any model allowed. **Set-but-empty** = deny all (fail-closed). Evaluated once at process start, so set it in your MCP client's `env` block (not via a dotenv loaded later). |
  274. ## 💻 Development
  275. 1. Clone the repository:
  276. ```bash
  277. git clone https://github.com/awkoy/replicate-flux-mcp.git
  278. cd replicate-flux-mcp
  279. ```
  280. 2. Install dependencies:
  281. ```bash
  282. npm install
  283. ```
  284. 3. Start the TypeScript watcher:
  285. ```bash
  286. npm run watch
  287. ```
  288. 4. Build the project:
  289. ```bash
  290. npm run build
  291. ```
  292. 5. Smoke-test the server with the MCP Inspector:
  293. ```bash
  294. npm run inspector
  295. ```
  296. 6. Connect to Client:
  297. ```json
  298. {
  299. "mcpServers": {
  300. "image-generation-mcp": {
  301. "command": "npx",
  302. "args": [
  303. "/Users/{USERNAME}/{PATH_TO}/replicate-flux-mcp/build/index.js"
  304. ],
  305. "env": {
  306. "REPLICATE_API_TOKEN": "YOUR REPLICATE API TOKEN"
  307. }
  308. }
  309. }
  310. }
  311. ```
  312. ### Testing
  313. This project currently has no automated test suite. Verification is done via:
  314. - `npm run build` — TypeScript type-checking catches most regressions.
  315. - `npm run inspector` — drives the built binary through the official MCP Inspector for end-to-end smoke testing of tools, resources, and prompts.
  316. Contributions adding a proper test framework (e.g. Vitest + an MCP stdio client harness) are welcome.
  317. ## ⚙️ Technical Details
  318. ### Stack
  319. - **Model Context Protocol SDK** - Core MCP functionality for tool and resource management
  320. - **Replicate API** - Provides access to state-of-the-art AI image generation models
  321. - **TypeScript** - Ensures type safety and leverages modern JavaScript features
  322. - **Zod** - Implements runtime type validation for robust API interactions
  323. ### Configuration
  324. The server can be configured by modifying the `CONFIG` object in `src/config/index.ts` or by setting the `REPLICATE_IMAGE_MODEL_ID` / `REPLICATE_SVG_MODEL_ID` environment variables to override the defaults:
  325. ```typescript
  326. export const CONFIG = {
  327. serverName: "replicate-flux-mcp",
  328. serverVersion: "0.4.1",
  329. imageModelId: process.env.REPLICATE_IMAGE_MODEL_ID ?? "black-forest-labs/flux-schnell",
  330. svgModelId: process.env.REPLICATE_SVG_MODEL_ID ?? "recraft-ai/recraft-v3-svg",
  331. pollingAttempts: 25,
  332. pollingInterval: 2000, // ms
  333. modelAllowlistConfigured: process.env.REPLICATE_MODEL_ALLOWLIST !== undefined,
  334. modelAllowlist: (process.env.REPLICATE_MODEL_ALLOWLIST ?? "")
  335. .split(",")
  336. .map((s) => s.trim())
  337. .filter(Boolean),
  338. };
  339. ```
  340. #### Switching models (no code changes)
  341. Use env vars when launching the server (works with `npx`, Cursor, Claude Desktop, etc.). Curated image/SVG tool overrides must be in the built-in allowlists:
  342. ```bash
  343. # Stay on defaults:
  344. REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp
  345. # Switch to other allowlisted models
  346. REPLICATE_IMAGE_MODEL_ID="google/imagen-4" \
  347. REPLICATE_SVG_MODEL_ID="recraft-ai/recraft-v3-svg" \
  348. REPLICATE_API_TOKEN=YOUR_TOKEN \
  349. npx -y replicate-flux-mcp
  350. ```
  351. `modelAllowlist` is evaluated once at process start from `REPLICATE_MODEL_ALLOWLIST`. Restart the server after changing it.
  352. ## 🔍 Troubleshooting
  353. ### Common Issues
  354. #### Authentication Error
  355. - Ensure your `REPLICATE_API_TOKEN` is correctly set in the environment
  356. - Verify your token is valid by testing it with the Replicate API directly
  357. #### Safety Filter Triggered
  358. - The model has a built-in safety filter that may block certain prompts
  359. - Try modifying your prompt to avoid potentially problematic content
  360. #### Timeout Error
  361. - For larger images or busy servers, you might need to increase `pollingAttempts` or `pollingInterval` in the configuration
  362. - Default settings should work for most use cases
  363. ## 🤝 Contributing
  364. Contributions are welcome! Please follow these steps to contribute:
  365. 1. Fork the repository
  366. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  367. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  368. 4. Push to the branch (`git push origin feature/amazing-feature`)
  369. 5. Open a Pull Request
  370. For feature requests or bug reports, please create a GitHub issue. If you like this project, consider starring the repository!
  371. ## 📄 License
  372. This project is licensed under the MIT License - see the LICENSE file for details.
  373. ## 🔗 Resources
  374. - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
  375. - [Replicate API Documentation](https://replicate.com/docs)
  376. - [Try for Free Collection](https://replicate.com/collections/try-for-free)
  377. - [Flux Schnell Model](https://replicate.com/black-forest-labs/flux-schnell)
  378. - [Recraft V3 SVG Model](https://replicate.com/recraft-ai/recraft-v3-svg)
  379. - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
  380. - [Smithery Documentation](https://smithery.ai/docs)
  381. - [Glama.ai MCP Servers](https://glama.ai/mcp/servers)
  382. - [Author: Yaroslav Boiko](https://yaroslavboiko.com)
  383. ## 🎨 Examples
  384. ![Demo](https://github.com/user-attachments/assets/ad6db606-ae3a-48db-a1cc-e1f88847769e)
  385. | Multiple Prompts | Prompt Variants |
  386. |-----------------|-----------------|
  387. | ![Multiple prompts example: "A serene mountain lake at sunset", "A bustling city street at night", "A peaceful garden in spring"](https://github.com/user-attachments/assets/e5ac56d2-bfbb-4f33-938c-a3d7bffeee60) | ![Variants example: Base prompt "A majestic castle" with modifiers "in watercolor style", "as an oil painting", "with gothic architecture"](https://github.com/user-attachments/assets/8ebe5992-4803-4bf3-a82a-251135b0698a) |
  388. Here are some examples of how to use the tools:
  389. ### Batch Image Generation with `generate_multiple_images`
  390. Create multiple distinct images at once with different prompts:
  391. ```json
  392. {
  393. "prompts": [
  394. "A red sports car on a mountain road",
  395. "A blue sports car on a beach",
  396. "A vintage sports car in a city street"
  397. ]
  398. }
  399. ```
  400. ### Image Variants with `generate_image_variants`
  401. Create different interpretations of the same concept using seeds:
  402. ```json
  403. {
  404. "prompt": "A futuristic city skyline at night",
  405. "num_variants": 4,
  406. "seed": 42
  407. }
  408. ```
  409. Or explore style variations with prompt modifiers:
  410. ```json
  411. {
  412. "prompt": "A character portrait",
  413. "prompt_variations": [
  414. "in anime style",
  415. "in watercolor style",
  416. "in oil painting style",
  417. "as a 3D render"
  418. ]
  419. }
  420. ```
  421. ---
  422. Made with ❤️ by Yaroslav Boiko

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.