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

Models and quality

Capability	grok-imagine-image	grok-imagine-image-2.0
Default model	Yes	Select per call or set XAI_IMAGE_MODEL
Source images per edit	1–3	1–5
Resolution	1k, 2k	1k, 2k
Quality parameter	—	low, medium, auto
Additional aspect ratios	—	21:9, 5:2

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:

Parameter	Type	Description
prompt	string, required	Image description or editing instructions
model	string	One of the two models above
n	integer	Output count, 1–10; default 1
aspect_ratio	string	Generation defaults to auto; editing follows the first input
resolution	string	1k or 2k; default 1k
quality	string	2.0: low, medium, auto
response_format	string	url (default) or b64_json for inline MCP image content
storage_options	object	Save generated images to the Files API

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" }]
}

Storage option	Description
filename	Required filename for the stored image
expires_after	File lifetime in seconds, 3600–2592000; default: permanent
public_url	true creates a shareable public link; default: private
public_url.expires_after	Use public_url: { "expires_after": 86400 } to set a link lifetime

See xAI storage documentation for details.

Configuration and networking

Environment variable	Description
XAI_API_KEY	xAI API key; takes precedence over XAIAPI_KEY
XAIAPI_KEY	Alternative API-key variable
XAI_IMAGE_MODEL	Default model; grok-imagine-image when omitted
XAIAPI_BASE_URL	API base URL; default https://api.x.ai/v1
XAI_TIMEOUT_MS	Request timeout in milliseconds; default 180000
HTTPS_PROXY	Network proxy for API requests; takes precedence over HTTP_PROXY
HTTP_PROXY	Network proxy, e.g. http://127.0.0.1:7890
IMAGE_PROXY_DOMAIN	Reverse proxy for returned imgen.x.ai URLs, e.g. https://images.example.com

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

模型与质量

能力	grok-imagine-image	grok-imagine-image-2.0
默认模型	是	每次调用指定，或设置 XAI_IMAGE_MODEL
编辑源图数量	1–3 张	1–5 张
分辨率	1k、2k	1k、2k
质量参数	—	low、medium、auto
新增宽高比	—	21:9、5:2

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

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

工具参数

两个工具共用以下参数：

参数	类型	说明
prompt	string，必填	图片描述或编辑指令
model	string	上表中的模型之一
n	integer	输出数量，1–10，默认 1
aspect_ratio	string	生成默认 auto；编辑默认跟随第一张源图
resolution	string	1k 或 2k，默认 1k
quality	string	2.0：low、medium、auto
response_format	string	默认 url；b64_json 返回 MCP 原生图片内容
storage_options	object	将输出保存至 Files API

宽高比支持 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" }]
}

存储选项	说明
filename	必填，存储文件名
expires_after	文件有效期，3600–2592000 秒；默认永久保存
public_url	设为 true 创建公开分享链接；默认为私有存储
public_url.expires_after	使用 public_url: { "expires_after": 86400 } 指定公开链接有效期

详见 xAI 存储文档。

环境变量与网络

变量	说明
XAI_API_KEY	API 密钥，优先于 XAIAPI_KEY
XAIAPI_KEY	API 密钥的另一个变量名
XAI_IMAGE_MODEL	默认模型，未设置时为 grok-imagine-image
XAIAPI_BASE_URL	API 基础地址，默认 https://api.x.ai/v1
XAI_TIMEOUT_MS	请求超时毫秒数，默认 180000
HTTPS_PROXY	API 网络代理，优先于 HTTP_PROXY
HTTP_PROXY	API 网络代理，例如 http://127.0.0.1:7890
IMAGE_PROXY_DOMAIN	返回图片的反向代理地址，例如 https://images.example.com

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

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

开发

npm ci
npm test

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

许可证

MIT