recraft-mcp

MCP server for AI image generation, transformation, and style management via the Recraft API

---

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

Detailed Parameter Reference

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.

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