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](https://modelcontextprotocol.io/).
- **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](https://www.recraft.ai/profile/api)
## Installation
### Claude Desktop
Add to your config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```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):
```json
{
"servers": {
"recraft": {
"command": "npx",
"args": ["-y", "recraft-mcp"],
"env": {
"RECRAFT_API_TOKEN": "your-api-token"
}
}
}
}
```
### Claude Code
```bash
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`):
```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`):
```json
{
"mcpServers": {
"recraft": {
"command": "npx",
"args": ["-y", "recraft-mcp"],
"env": {
"RECRAFT_API_TOKEN": "your-api-token"
}
}
}
}
```
### Docker
```bash
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:
```json
{
"mcpServers": {
"recraft": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "RECRAFT_API_TOKEN=your-api-token",
"ghcr.io/bartwaardenburg/recraft-mcp-server:latest"
]
}
}
}
```
### Smithery
```bash
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](https://modelcontextprotocol.io/docs/concepts/tools#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](https://www.recraft.ai/profile/api) | — |
| `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:
```bash
# 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](SECURITY.md) for reporting vulnerabilities.
## Development
```bash
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](CONTRIBUTING.md) for guidelines.
## License
[MIT](LICENSE)