grok-image

mcp-server-grok-image

用于 xAI Grok 图像生成 API 的 MCP（Model Context Protocol）服务。使用 Rust 构建，将图像生成和编辑功能作为 MCP 工具提供。

与所有 MCP 服务一样，通过 stdio 使用 JSON-RPC 2.0 通信。

工具

工具	描述
generate_image	根据文本提示词生成图像
edit_image	使用自然语言指令编辑现有图像
headshot	根据源肖像生成企业头像（填充至 3:2 + 固定编辑提示词）
list_styles	列出可用于 generate_image 的图像风格

generate_image

根据文本描述生成图像。

参数：

名称	类型	必填	描述
prompt	string	是	所需图像的文本描述
model	string	否	使用的模型（默认：grok-imagine-image-2.0）
n	integer	否	要生成的图像数量（1-10，默认 1）
aspect_ratio	string	否	宽高比：1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20、21:9、5:2、auto
resolution	string	否	输出分辨率：1k（约 1024px，默认）或 2k（约 2048px）
quality	string	否	low、medium 或 auto（仅限 2.0；省略时为 auto。目前 auto 在生成时会使用 low）
response_format	string	否	输出格式：url（默认，临时）或 b64_json
style	string	否	要应用的风格名称（使用 list_styles 查看选项）

设置风格后，提示词会套用该风格的模板。例如，使用 style: "watercolor" 和 prompt: "a cat on a roof" 时，API 会收到 "a cat on a roof, as a watercolor painting"。使用此参数时，请避免在提示词中加入风格描述。

响应中包含解析后的提示词，以便查看实际发送给 API 的内容。

edit_image

使用自然语言指令编辑现有图像。

参数：

名称	类型	必填	描述
image_url	string	否*	源图像的 URL、base64 数据 URI 或本地文件路径。不能与 images 同时使用。
images	string[]	否*	最多 5 张用于多图编辑的源图像。在提示词中使用 <IMAGE_0>、<IMAGE_1>、… 引用它们
prompt	string	是	自然语言编辑指令
model	string	否	使用的模型（默认：grok-imagine-image-2.0）
n	integer	否	要生成的变体数量（1-10，默认 1）
aspect_ratio	string	否	与 generate_image 相同的选项，包括 21:9 和 5:2
resolution	string	否	输出分辨率：1k（约 1024px，默认）或 2k（约 2048px）
quality	string	否	low、medium 或 auto（仅限 2.0；省略时为 auto。目前 auto 在编辑时会使用 medium）
response_format	string	否	输出格式：url（默认，临时）或 b64_json

* 请提供 image_url 或 images 中的一个。

注意：edit_image 有意不提供 style 参数——编辑提示词是指令（例如“移除背景”），而不是描述，因此套用风格模板会产生无意义的结果。

headshot

仅扩展人像修复（Imagine 上等效于 Gemini 流程）。不会重新调整姿势构图、抠出头发或重新设计人物。

1. 调整完整源图的大小（默认宽度为 550px）——绝不裁剪
2. 使用白色边栏填充至画布宽度（默认 780）
3. 以中等质量调用 grok-imagine-image-2.0：必要时补全被截断的肩膀；使用干净的纯白色背景；保留面部、头发、姿势、服装和徽标

不抠图／不使用 rembg／不使用透明 alpha——与原始 Gemini 人像修复技能的用途相同。

参数：

Name	Type	Required	Description
image	string	yes	本地路径、http(s) URL 或 data: URI
clothing	string	no	仅用于补全缺失的肩膀部分
notes	string	no	必须保留的细节（眼镜、准确的徽标文字等）
pronoun	string	no	his / her / their（默认 their）
gravity	string	no	边栏填充对齐方式（默认 North）
content_width	integer	no	填充前调整后的宽度（默认 550）
canvas_width	integer	no	填充后的宽度（默认 780）
resolution	string	no	1k 或 2k（默认 2k）
output_path	string	no	可选的最终路径（也位于 save_dir 下）
n	integer	no	变体数量（1–10，默认 1）
quality	string	no	low / medium / auto（默认 medium）
model	string	no	默认 grok-imagine-image-2.0

填充后的中间文件：save_dir/headshot-padded_*.jpg。

list_styles

返回所有可用图像风格及其名称、描述和提示词模板。无参数。

内置风格

Style	Description
watercolor	水彩画风格
oil-painting	带有明显笔触的油画
pencil-sketch	细致的铅笔素描
pixel-art	复古像素艺术
anime	动漫风格插画
pop-art	大胆的波普艺术风格
art-nouveau	带有流畅有机线条的新艺术风格
cinematic	采用戏剧性灯光的电影摄影风格
portrait	专业人像摄影
macro	极致微距摄影
aerial	航拍无人机摄影
studio	以干净背景拍摄的影棚摄影
noir	暗调黑色电影风格
vintage	褪色的复古照片

可用模型

Model	Notes
grok-imagine-image-2.0（默认）	可选 quality（low / medium / auto），最多 5 个编辑参考，支持 21:9 和 5:2。目前，生成时 auto 会使用 low，编辑时会使用 medium。
grok-imagine-image	1.0。仍可使用；无 quality 参数。
grok-imagine-image-quality	将于 2026-11-02 停用。此后，该 slug 将由 grok-imagine-image-2.0 以 quality: low 提供服务（每张图比质量模型便宜 $0.01）。

前置条件

• Rust（edition 2024）
• 从 console.x.ai 获取的 xAI API 密钥

设置

创建配置文件：

mkdir -p ~/.config/mcp-server-grok-image

创建 ~/.config/mcp-server-grok-image/config.toml：

api_key = "xai-..."

自定义风格

在配置文件中添加自定义风格。与内置风格同名的自定义风格会覆盖内置风格。

api_key = "xai-..."

[[styles]]
name = "my-style"
description = "My custom look"
template = "{prompt}, in my custom style"

[[styles]]
name = "watercolor"
description = "My watercolor variant"
template = "{prompt}, as a loose expressive watercolor with ink outlines"

模板必须包含 {prompt} 占位符。任何缺少该占位符的自定义风格都会在启动时跳过，并显示警告。

构建

cargo build --release

这会生成 target/release/mcp-server-grok-image。

开发时：

cargo build              # debug build
cargo run                # run in dev mode
RUST_LOG=debug cargo run # run with debug logging

MCP 配置

将以下内容添加到 Claude Desktop 配置（~/.config/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "grok-image": {
      "command": "/path/to/mcp-server-grok-image"
    }
  }
}

项目结构

src/
  main.rs      process entry (stdio MCP)
  config.rs    TOML / env config
  styles.rs    built-in + custom styles
  grok.rs      xAI request/response types
  params.rs    MCP tool params + validation
  image_io.rs  data URIs, local files, mime, fetch
  headshot.rs  letterbox pad + expand prompt
  server.rs    MCP tools and Grok HTTP

许可证

MIT