Recraft MCP Server

recraft-mcp

通过 Recraft API 实现 AI 图像生成、转换和风格管理的 MCP 服务

---

注意： 这是一个非官方、由社区维护的项目，与 Recraft 没有关联，也未获其认可。

通过 Model Context Protocol 使用 16 个工具，实现图像生成、处理和风格管理。

• 生成 — 文本生成图像、图像生成图像、局部重绘、背景替换和生成
• 处理 — 移除背景、擦除区域、矢量化（SVG）、清晰和创意放大
• 风格 — 根据参考图像创建自定义风格，列出／获取／删除风格
• 账户 — 查看剩余额度和用户信息（包含在 styles 工具集中）
• 可配置 — 筛选工具集、调整缓存 TTL、控制重试

先决条件

• Node.js 20+（或 Docker）
• Recraft API 令牌

安装

Claude Desktop

添加到配置文件：

• 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

添加到工作区中的 .vscode/mcp.json（或使用上方的一键安装按钮）：

{
  "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

添加到 Cursor 的 MCP 设置（~/.cursor/mcp.json）：

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

Windsurf

添加到 Windsurf 的 MCP 配置（~/.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

在任何 MCP 客户端中使用 Docker，只需替换命令：

{
  "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

工具

生成

工具	描述
generate_image	根据文本提示词生成图像，并提供风格、尺寸和艺术效果控制
image_to_image	根据文本提示词转换现有图像，并可调整转换强度
inpaint_image	根据文本提示词填充图像中的蒙版区域
replace_background	替换背景，同时保留前景主体
generate_background	为图像的蒙版区域生成背景

处理

工具	描述
remove_background	移除背景并保留透明效果
erase_region	无缝擦除图像中的蒙版区域
vectorize_image	将栅格图像转换为可缩放的 SVG 矢量图
crisp_upscale	放大图像，同时清晰保留细节
creative_upscale	放大图像，并通过创意增强添加细节

风格与账户

工具	描述
create_style	根据 1-5 张参考图像创建自定义风格
get_style	根据 ID 获取自定义风格的详细信息
list_styles	列出所有自定义风格
list_basic_styles	列出可用的精选风格
delete_style	删除自定义风格
get_current_user	获取用户信息和剩余点数

工具注释

所有工具都包含 MCP 工具注释，帮助客户端了解其行为：

工具	只读	开放世界
generate_image		是
image_to_image		是
inpaint_image		是
replace_background		是
generate_background		是
remove_background		是
erase_region		是
vectorize_image		是
crisp_upscale		是
creative_upscale		是
create_style		是
get_style	是	是
list_styles	是	是
list_basic_styles	是	是
delete_style		是
get_current_user	是	是

参数详细参考

generate_image

参数	类型	必填	描述
prompt	string	是	文本描述（V2/V3 最多 1000 个字符，V4 最多 10000 个字符）
model	enum		recraftv3（默认）、recraftv4、recraftv4_vector、recraftv2、recraft20b、refm1
style	enum		realistic_image（默认）、digital_illustration、vector_illustration、icon、logo_raster
substyle	string		子风格细化（例如 b_and_w、pixel_art、watercolor）
style_id	uuid		自定义风格 ID（不能与 style/substyle 同时使用）
size	enum		图像尺寸，例如 1024x1024（默认）、1365x1024、1536x1024 等
n	integer		要生成的图像数量（1-6，默认 1）
negative_prompt	string		图像中需要避免的内容
artistic_level	integer		0（简单）到 5（动态）
no_text	boolean		防止图像中出现文字
image_format	enum		webp 或 png
random_seed	integer		用于生成可复现结果的种子

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.

配置

环境变量	描述	默认值
RECRAFT_API_TOKEN	必填。 您的 Recraft API 令牌	—
RECRAFT_TOOLSETS	要启用的工具集，以逗号分隔：generation、processing、styles	全部
RECRAFT_CACHE_TTL	缓存 TTL（秒）（设为 0 可禁用）	120
RECRAFT_MAX_RETRIES	遇到速率限制（429）时的最大重试次数	3

工具集筛选

只启用所需的工具集，减少向大模型公开的工具数量：

# Only image generation
RECRAFT_TOOLSETS=generation

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

支持的模型

模型	描述
recraftv3	Recraft V3（默认）
recraftv4	Recraft V4（最新栅格模型）
recraftv4_vector	Recraft V4 Vector（SVG 输出）
recraftv2	Recraft V2
recraft20b	Recraft 20B（旧版）
refm1	RefM1

注意： V4 模型不支持 style 参数；请使用提示词控制风格。

支持的风格

风格	子风格
realistic_image（默认）	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_to_image、inpaint_image、remove_background 等）支持：

• URL — 任何可公开访问的 HTTP(S) URL
• Base64 — 原始 Base64 编码的图像数据

安全

• API 令牌 — 您的 RECRAFT_API_TOKEN 仅会发送至 Recraft API（https://external.api.recraft.ai）。它不会被记录，也不会在进程生命周期结束后继续存储。
• 图像数据 — 图像会发送至 Recraft 的服务器进行处理。磁盘上不会缓存任何图像数据。
• 网络访问 — 此服务会向 external.api.recraft.ai 和 registry.npmjs.org（用于检查更新）发起出站 HTTPS 请求。

如需报告漏洞，请参阅 SECURITY.md。

开发

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

请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT