<p align="center">
<h1 align="center">recraft-mcp</h1>
<p align="center">
MCP server for AI image generation, transformation, and style management via the <a href="https://www.recraft.ai/api">Recraft API</a>
</p>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/recraft-mcp"></a>
<a href="https://www.npmjs.com/package/recraft-mcp"></a>
<a href="https://github.com/BartWaardenburg/recraft-mcp-server/blob/main/LICENSE"></a>
<a href="https://github.com/BartWaardenburg/recraft-mcp-server/actions/workflows/ci.yml"></a>
<a href="https://www.typescriptlang.org/"></a>
<a href="https://nodejs.org/"></a>
<a href="https://smithery.ai/server/recraft-mcp"></a>
</p>

<p align="center">
<a href="https://vscode.dev/redirect/mcp/install?name=recraft&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22api_token%22%2C%22description%22%3A%22Recraft+API+Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22recraft-mcp%22%5D%2C%22env%22%3A%7B%22RECRAFT_API_TOKEN%22%3A%22%24%7Binput%3Aapi_token%7D%22%7D%7D"></a>
<a href="https://vscode.dev/redirect/mcp/install?name=recraft&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22api_token%22%2C%22description%22%3A%22Recraft+API+Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22-e%22%2C%22RECRAFT_API_TOKEN%3D%24%7Binput%3Aapi_token%7D%22%2C%22ghcr.io%2Fbartwaardenburg%2Frecraft-mcp-server%3Alatest%22%5D%7D"></a>
</p>

---

> Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by Recraft.

16 tools for image generation, processing, and style management — all accessible through the Model Context Protocol.

- Generate — Text-to-image, image-to-image, inpainting, background replacement & generation
- Process — Background removal, region erasing, vectorization (SVG), crisp & creative upscaling
- Styles — Create custom styles from reference images, list/get/delete styles
- Account — Check remaining credits and user info (included in styles toolset)
- Configurable — Filter toolsets, adjust cache TTL, control retries

Prerequisites

- Node.js 20+ (or Docker)
- A Recraft API token

Installation

Claude Desktop

Add to your config file:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "recraft": {
      "command": "npx",
      "args": ["-y", "recraft-mcp"],
      "env": {
        "RECRAFT_API_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace (or use the one-click install buttons above):

{
  "servers": {
    "recraft": {
      "command": "npx",
      "args": ["-y", "recraft-mcp"],
      "env": {
        "RECRAFT_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

claude mcp add recraft-mcp -e RECRAFT_API_TOKEN=your-api-token -- npx -y recraft-mcp

Cursor

Add to Cursor's MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "recraft": {
      "command": "npx",
      "args": ["-y", "recraft-mcp"],
      "env": {
        "RECRAFT_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windsurf

Add to Windsurf's MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "recraft": {
      "command": "npx",
      "args": ["-y", "recraft-mcp"],
      "env": {
        "RECRAFT_API_TOKEN": "your-api-token"
      }
    }
  }
}

Docker

docker run --rm -i -e RECRAFT_API_TOKEN="your-api-token" ghcr.io/bartwaardenburg/recraft-mcp-server:latest

Use Docker in any MCP client by replacing the command:

{
  "mcpServers": {
    "recraft": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "RECRAFT_API_TOKEN=your-api-token",
        "ghcr.io/bartwaardenburg/recraft-mcp-server:latest"
      ]
    }
  }
}

Smithery

npx -y @smithery/cli install recraft-mcp --client claude

Tools

Generation

| Tool | Description |
|------|-------------|
| generate_image | Generate images from a text prompt with style, size, and artistic controls |
| image_to_image | Transform an existing image based on a text prompt with adjustable strength |
| inpaint_image | Fill in masked regions of an image based on a text prompt |
| replace_background | Replace the background while preserving the foreground subject |
| generate_background | Generate a background for masked areas of an image |

Processing

| Tool | Description |
|------|-------------|
| remove_background | Remove the background, leaving transparency |
| erase_region | Seamlessly erase a masked region from an image |
| vectorize_image | Convert raster images to scalable SVG vectors |
| crisp_upscale | Upscale with sharp detail preservation |
| creative_upscale | Upscale with creative enhancement and added detail |

Styles & Account

| Tool | Description |
|------|-------------|
| create_style | Create a custom style from 1-5 reference images |
| get_style | Get details of a custom style by ID |
| list_styles | List all custom styles |
| list_basic_styles | List available curated styles |
| delete_style | Delete a custom style |
| get_current_user | Get user info and remaining credits |

Tool Annotations

All tools include MCP tool annotations to help clients understand their behavior:

| Tool | Read-only | Open-world |
|------|:---------:|:----------:|
| generate_image | | Yes |
| image_to_image | | Yes |
| inpaint_image | | Yes |
| replace_background | | Yes |
| generate_background | | Yes |
| remove_background | | Yes |
| erase_region | | Yes |
| vectorize_image | | Yes |
| crisp_upscale | | Yes |
| creative_upscale | | Yes |
| create_style | | Yes |
| get_style | Yes | Yes |
| list_styles | Yes | Yes |
| list_basic_styles | Yes | Yes |
| delete_style | | Yes |
| get_current_user | Yes | Yes |

<details>
<summary><strong>Detailed Parameter Reference</strong></summary>

generate_image

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| prompt | string | Yes | Text description (max 1000 chars V2/V3, 10000 V4) |
| model | enum | | recraftv3 (default), recraftv4, recraftv4_vector, recraftv2, recraft20b, refm1 |
| style | enum | | realistic_image (default), digital_illustration, vector_illustration, icon, logo_raster |
| substyle | string | | Substyle refinement (e.g. b_and_w, pixel_art, watercolor) |
| style_id | uuid | | Custom style ID (mutually exclusive with style/substyle) |
| size | enum | | Image dimensions, e.g. 1024x1024 (default), 1365x1024, 1536x1024, etc. |
| n | integer | | Number of images to generate (1-6, default 1) |
| negative_prompt | string | | What to avoid in the image |
| artistic_level | integer | | 0 (simple) to 5 (dynamic) |
| no_text | boolean | | Prevent text in the image |
| image_format | enum | | webp or png |
| random_seed | integer | | Seed for reproducible results |

image_to_image

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Source image (URL or base64). Max 5MB, <16MP, max 4096px per side |
| prompt | string | Yes | Description of desired changes |
| strength | number | Yes | Change magnitude: 0.0 (minimal) to 1.0 (maximum) |
| model | enum | | Model to use |
| style | enum | | Style category (not supported for V4) |
| substyle | string | | Substyle refinement |
| style_id | uuid | | Custom style ID |
| n | integer | | Number of outputs (1-6) |
| negative_prompt | string | | What to avoid |
| image_format | enum | | webp or png |
| random_seed | integer | | Seed for reproducibility |

inpaint_image

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Source image (URL or base64) |
| mask | string | Yes | Grayscale PNG mask (white = inpaint, black = preserve) |
| prompt | string | Yes | What to generate in the masked area |
| model, style, substyle, style_id, n, negative_prompt, image_format, random_seed | | | Same as generate_image |

replace_background

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Source image (URL or base64) |
| prompt | string | Yes | Description of the new background |
| model, style, substyle, style_id, n, negative_prompt, image_format, random_seed | | | Same as generate_image |

generate_background

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Source image (URL or base64) |
| mask | string | Yes | Mask defining the background area |
| prompt | string | Yes | Description of the background to generate |
| model, style, substyle, style_id, n, negative_prompt, image_format, random_seed | | | Same as generate_image |

remove_background

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Image (URL or base64) |
| image_format | enum | | webp or png |

erase_region

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Source image (URL or base64) |
| mask | string | Yes | Grayscale mask (white = erase, black = preserve) |
| image_format | enum | | webp or png |

vectorize_image

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Image to vectorize (URL or base64) |

crisp_upscale

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Image to upscale (URL or base64). Max 5MB, <4MP |
| image_format | enum | | webp or png |

creative_upscale

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| image | string | Yes | Image to upscale (URL or base64). Max 5MB, <16MP |
| image_format | enum | | webp or png |

create_style

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| images | string[] | Yes | 1-5 reference images (URLs or base64) |
| style | enum | Yes | Base style category |

get_style

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| style_id | uuid | Yes | Style ID to retrieve |

delete_style

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| style_id | uuid | Yes | Style ID to delete |

list_styles, list_basic_styles, get_current_user

No parameters required.

</details>

Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| RECRAFT_API_TOKEN | Required. Your Recraft API token | — |
| RECRAFT_TOOLSETS | Comma-separated toolsets to enable: generation, processing, styles | All |
| RECRAFT_CACHE_TTL | Cache TTL in seconds (0 to disable) | 120 |
| RECRAFT_MAX_RETRIES | Max retry attempts on rate limit (429) | 3 |

Toolset Filtering

Reduce the number of tools exposed to the LLM by enabling only what you need:

# Only image generation
RECRAFT_TOOLSETS=generation
Generation + processing, no style management
RECRAFT_TOOLSETS=generation,processing

Supported Models

| Model | Description |
|-------|-------------|
| recraftv3 | Recraft V3 (default) |
| recraftv4 | Recraft V4 (latest raster) |
| recraftv4_vector | Recraft V4 Vector (SVG output) |
| recraftv2 | Recraft V2 |
| recraft20b | Recraft 20B (legacy) |
| refm1 | RefM1 |

> Note: V4 models do not support the style parameter — use the prompt to control style.

Supported Styles

| Style | Substyles |
|-------|-----------|
| realistic_image (default) | b_and_w, enterprise, hard_flash, hdr, motion_blur, natural_light, studio_portrait |
| digital_illustration | pixel_art, hand_drawn, grain, infantile_sketch, 2d_art_poster, handmade_3d, engraving, comic_book |
| vector_illustration | bold_stroke, chemistry, colored_stencil, contour_pop_art, flat_2, line_art, line_circuit |
| icon | broken_line, colored_outline, colored_shapes, doodle_fill, doodle_offset_fill, offset_fill, outline |
| logo_raster | — |

Image Input

Tools that accept images (image_to_image, inpaint_image, remove_background, etc.) support:

- URL — Any publicly accessible HTTP(S) URL
- Base64 — Raw base64-encoded image data

Security

- API token — Your RECRAFT_API_TOKEN is sent only to the Recraft API (https://external.api.recraft.ai). It is never logged or stored beyond the process lifetime.
- Image data — Images are sent to Recraft's servers for processing. No image data is cached on disk.
- Network access — This server makes outbound HTTPS requests to external.api.recraft.ai and registry.npmjs.org (for update checks).

See SECURITY.md for reporting vulnerabilities.

Development

pnpm install         # Install dependencies
pnpm dev             # Run with tsx (hot reload)
pnpm build           # Compile TypeScript
pnpm test            # Run tests
pnpm typecheck       # Type check

See CONTRIBUTING.md for guidelines.

License

MIT