Grok Image MCP

English | 中文

An MCP server for generating and editing images with the xAI image API. Supports model and quality selection, local images, stored files, and inline image results over stdio.

Requires Node.js 22.19+ and an xAI API key.

Quick start

Add this to your MCP client's configuration:

{
  "mcpServers": {
    "grok_image": {
      "command": "npx",
      "args": ["-y", "grok-image-mcp"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

The server exposes generate_image and edit_image. Example generate_image arguments:

{
  "prompt": "A watercolor illustration of a quiet mountain lake",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "aspect_ratio": "16:9"
}

Related MCP server: image-studio-mcp

Models and quality

The model argument overrides XAI_IMAGE_MODEL. The default is grok-imagine-image.

On 2.0, quality defaults to auto: low for generation and medium for editing. See xAI pricing for costs.

Tools

Both tools accept these parameters:

Aspect ratios: 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, auto; 2.0 additionally supports 21:9 and 5:2.

Editing

For edit_image, supply one of these source lists:

• image_urls: ordered array of public URLs, base64 data URIs, or local paths.

• images: ordered array of { "url": "..." } or { "file_id": "..." } objects. url also accepts data URIs and local paths.

{
  "prompt": "Replace the background with a snowy forest",
  "image_urls": ["/absolute/path/to/photo.png"]
}

Local files support PNG, JPEG and WebP. Relative paths resolve from the server's working directory.

Results

structuredContent.images contains image URLs, revised prompts, MIME types and stored-file metadata. Model, quality and usage are included when returned by xAI.

• url: temporary image links, also returned as Markdown. Use storage_options to save images.

• b64_json: MCP image content blocks, with inline: true in the corresponding structured entry.

Save images and reuse them

Add storage_options to either tool to persist output in the xAI Files API:

{
  "prompt": "A small cabin in a pine forest",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "storage_options": {
    "filename": "cabin.jpg",
    "expires_after": 86400
  }
}

This saves the image privately for one day. Use structuredContent.images[0].file_output.file_id in a subsequent edit:

{
  "prompt": "Change the season to winter",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "images": [{ "file_id": "file-id-from-the-previous-result" }]
}

See xAI storage documentation for details.

Configuration and networking

For IMAGE_PROXY_DOMAIN, configure your reverse proxy to forward paths and query strings to https://imgen.x.ai.

For long generations, set the MCP client's tool timeout to XAI_TIMEOUT_MS or longer.

Development

npm ci
npm test

To use a local build, configure your MCP client to run node with the absolute path to dist/index.js.

License

MIT

基于 xAI 图像 API 的 MCP 服务，支持选择模型与质量、编辑本地图片或已存储的图片，并返回图片链接或内联图片。使用 stdio 传输。

需要 Node.js 22.19+ 和 xAI API 密钥。

快速开始

在 MCP 客户端中添加：

{
  "mcpServers": {
    "grok_image": {
      "command": "npx",
      "args": ["-y", "grok-image-mcp"],
      "env": {
        "XAI_API_KEY": "你的 xAI API 密钥"
      }
    }
  }
}

服务提供 generate_image 和 edit_image 两个工具。generate_image 调用示例：

{
  "prompt": "一幅宁静山间湖泊的水彩插画",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "aspect_ratio": "16:9"
}

模型与质量

调用时的 model 优先于环境变量 XAI_IMAGE_MODEL，默认值为 grok-imagine-image。

2.0 的质量默认为 auto：生成对应 low，编辑对应 medium。费用见 xAI 定价。

工具参数

两个工具共用以下参数：

宽高比支持 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、auto；2.0 还支持 21:9、5:2。

编辑图片

edit_image 的源图列表使用以下一种形式：

• image_urls：按顺序提供公开 URL、base64 data URI 或本地路径。

• images：按顺序提供 { "url": "..." } 或 { "file_id": "..." } 对象。url 也接受 data URI 和本地路径。

{
  "prompt": "将背景替换成雪中的森林",
  "image_urls": ["/absolute/path/to/photo.png"]
}

本地文件支持 PNG、JPEG、WebP。相对路径以服务的工作目录为基准。

返回结果

structuredContent.images 包含图片 URL、修改后的提示词、MIME 类型和文件存储信息；模型、质量、用量信息随 xAI 返回内容提供。

• url：临时图片链接，同时以 Markdown 返回。使用 storage_options 可保存图片。

• b64_json：MCP image 内容块，对应的结构化条目标记为 inline: true。

保存与复用图片

为任一工具添加 storage_options，即可保存输出：

{
  "prompt": "松林中的一间小木屋",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "storage_options": {
    "filename": "cabin.jpg",
    "expires_after": 86400
  }
}

上述配置将图片私有保存一天。从 structuredContent.images[0].file_output.file_id 取得文件 ID，随后编辑时复用：

{
  "prompt": "将季节改成冬季",
  "model": "grok-imagine-image-2.0",
  "quality": "low",
  "images": [{ "file_id": "上一次返回的文件 ID" }]
}

详见 xAI 存储文档。

环境变量与网络

使用 IMAGE_PROXY_DOMAIN 时，反向代理需将路径与查询参数转发到 https://imgen.x.ai。

生成耗时较长时，将 MCP 客户端的工具超时设为 XAI_TIMEOUT_MS 或更长。

开发

npm ci
npm test

使用本地构建时，在 MCP 客户端中配置 node 和 dist/index.js 的绝对路径。

许可证

MIT