Grok2 Image MCP Server

Grok Image MCP

English | 中文

使用 xAI image API 生成和编辑图像的 MCP 服务。支持模型和质量选择、本地图像、存储文件，以及通过 stdio 返回内联图像结果。

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

快速开始

将以下内容添加到 MCP 客户端的配置中：

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

该服务提供 generate_image 和 edit_image。generate_image 参数示例：

{
  "prompt": "A watercolor illustration of a quiet mountain lake",
  "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 数据 URI 或本地路径数组。
• images：按顺序排列的 { "url": "..." } 或 { "file_id": "..." } 对象数组。url 也接受数据 URI 和本地路径。

{
  "prompt": "Replace the background with a snowy forest",
  "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，即可将输出保存到 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
  }
}

这会将图像私密保存一天。在后续编辑中使用 structuredContent.images[0].file_output.file_id：

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

存储选项	说明
filename	存储图像的必填文件名
expires_after	文件有效期（秒），3600–2592000；默认值：永久
public_url	true 会创建可分享的公开链接；默认值：私密
public_url.expires_after	使用 public_url: { "expires_after": 86400 } 设置链接有效期

详情请参阅 xAI 存储文档。

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