z AI image gen MCP

Z.AI图像和视频生成MCP服务器

A. 模型上下文协议（MCP） 该服务器为LLM应用程序提供对Z.AI图像和视频生成模型的访问。

特性

• 图像生成：用于生成高质量图像的GLM Image和CogView-4型号
• 视频生成：用于AI视频创建的CogVideoX-3、Vidu Q1和Vidu 2模型
• 多种输入模式：文本到图像/视频、图像到视频、开始到结束帧动画
• 异步处理：提交长时间运行的任务并轮询结果
• 自动下载：在一次操作中生成和下载
• 自动检索：具有指数回退的内置重试逻辑
• 全面验证：带有明确错误消息的输入验证
• 类型安全：完全支持TypeScript，具有详细的类型定义

安装

npm install GeorgH93/z_ai_image_gen_mcp

配置

将Z.AI API键设置为环境变量：

export ZAI_API_KEY=your_api_key_here

从获取API密钥 Z.AI API密钥页 或注册 GLM 编程计划.

可选配置

用法

使用克劳德桌面

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "z-ai-image": {
      "command": "npx",
      "args": ["z-ai-image-mcp"],
      "env": {
        "ZAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

与其他MCP客户端

直接运行服务器：

npx z-ai-image-mcp

或者以编程方式：

import { createServer, loadConfig } from 'z-ai-image-mcp';

const config = loadConfig();
const server = createServer(config);
// Connect to your transport...

使用OpenCode

添加到您的OpenCode配置(opencode.json 或 opencode.jsonc 在项目根目录中）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

或者使用环境变量引用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "{env:ZAI_API_KEY}"
      }
    }
  }
}

使用OpenCode提示：

Generate a professional logo for a tech startup. use z-ai-image

或添加到您的 AGENTS.md:

When generating images, use the `z-ai-image` MCP server tools.

每个代理配置（可选）：

要仅为特定代理启用MCP服务器，请执行以下操作：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "{env:ZAI_API_KEY}"
      }
    }
  },
  "tools": {
    "z-ai-image*": false
  },
  "agent": {
    "design-agent": {
      "tools": {
        "z-ai-image*": true
      }
    }
  }
}

可用工具

1. list_models

列出所有可用的图像生成模型及其功能。

Use this tool to discover available models, their features, and recommended settings.

2. generate_image

从文本提示同步生成图像。

参数：

• prompt （必填）：图像的文字描述（最多4000个字符）
• model （可选）： glm-image 或 cogview-4-250304 （默认值： glm-image)
• size （可选）：图像尺寸。， 1280x1280 （默认值： 1280x1280)
• quality （可选）： hd 或 standard （默认值： hd GLM图像）
• user_id （可选）：用于防止滥用的最终用户ID（6-128个字符）

例子：

Generate an image of a cute kitten sitting on a windowsill with a sunset background.

3. generate_image_async

启动异步图像生成任务。返回轮询的任务ID。

参数：

• prompt （必填）：图像的文字描述
• model （可选）：仅限 glm-image 支持异步（默认： glm-image)
• size （可选）：图像尺寸（默认值： 1280x1280)
• quality （可选）：仅限 hd 支持异步（默认： hd)
• user_id （可选）：用于防止滥用的最终用户ID

例子：

Start async generation of a complex poster design.

4. get_async_result

检索异步图像生成任务的结果。

参数：

• task_id （必填）：任务ID来自 generate_image_async

例子：

Check the status of task ID "task-12345".

5. download_image

从URL下载图像并将其作为base64返回或保存到文件中。

参数：

• url （必填）：要下载的图像的URL（例如，从 generate_image 或 get_async_result)
• output （可选）： base64 或 file_output （默认值： base64)
• file_output （可选）：保存图像文件的绝对路径（如果输出为 file_output).例子： /path/to/image.png

输出模式：

• base64：直接以base64格式返回图像数据（如果>1MB，则自动切换到文件）
• file_output：将映像保存到指定路径的磁盘

例子：

Download the generated image and save it to /home/user/images/logo.png

注： Z.AI图像URL将在30天后过期。使用此工具下载并永久存储图像。

6. generate_and_download_image ⭐ 推荐

生成图像并在一次操作中自动下载。当您需要立即获取图像数据时，这是最方便的工具。

参数：

• prompt （必填）：图像的文字描述（最多4000个字符）
• model （可选）： glm-image 或 cogview-4-250304 （默认值： glm-image)
• size （可选）：图像尺寸。， 1280x1280 （默认值： 1280x1280)
• quality （可选）： hd 或 standard （默认值： hd GLM图像）
• user_id （可选）：用于防止滥用的最终用户ID（6-128个字符）
• output （可选）： base64 或 file_output （默认值： base64)
• file_output （可选）：保存图像文件的绝对路径（如果输出为 file_output)
• poll_interval （可选）：轮询异步结果之间的等待秒数（默认值：3）
• max_wait （可选）：等待生成的最长秒数（默认值：120）

输出模式：

• base64：直接以base64格式返回图像数据（如果>1MB，则自动切换到文件）
• file_output：将映像保存到指定路径的磁盘

示例：

# Generate and get as base64
Generate a logo for my company and show me the image.

# Generate and save to file
Generate a logo and save it to /home/user/images/logo.png

行为：

• 对于GLM-Image：使用带有自动轮询的异步API直到完成
• 对于CogView-4：使用同步API
• 生成完成后自动下载结果
• 以base64格式返回图像或保存到指定路径

______________________________________________________________________

视频生成工具

7. list_video_models

列出所有可用的视频生成模型及其功能。

Use this tool to discover available video models, their features, and supported parameters.

8. generate_video

从文本或图像异步生成视频。返回轮询的任务ID。

参数：

• model （必填）：视频生成模型

- cogvideox-3：Z.AI旗舰机型（最高4K，5-10s，音频支持） - viduq1-text：文本转视频，1080P，5秒 - viduq1-image：图像转视频，1080P，5秒 - viduq1-start-end：开始-结束帧，1080P，5秒 - vidu2-image：图像到视频，720P，4秒（更快，更便宜） - vidu2-start-end：开始-结束帧，720P，4秒 - vidu2-reference：基于参考，720P，4秒

• prompt （可选）：文本描述（最多512个字符）
• image_url （可选）：用于图像到视频生成的图像URL
• quality （CogVideoX-3）： quality 或 speed
• size （可选）：视频分辨率
• duration （可选）：视频持续时间（秒）
• fps （CogVideoX-3）：30或60
• with_audio （可选）：生成AI音效
• style （视频Q1文本）： general 或 anime
• aspect_ratio （视频Q1/2）： 16:9, 9:16，或 1:1
• movement_amplitude （视频）： auto, small, medium，或 large
• user_id （可选）：用于防止滥用的最终用户ID

示例：

# Text-to-video
Generate a video of a cat playing with a ball.

# Image-to-video
Animate this image: [image_url]

# Start-end frame
Create a smooth transition from [first_frame] to [last_frame].

9. get_video_result

检索异步视频生成任务的结果。

参数：

• task_id （必填）：任务ID来自 generate_video

注： 视频生成通常需要30秒到几分钟，具体取决于持续时间和质量。

10. generate_and_download_video ⭐ 推荐

生成视频并自动下载。轮询完成情况并保存视频文件。

参数：

• 所有参数来自 generate_video 加上：
• file_output （可选）：保存视频文件的绝对路径
• poll_interval （可选）：轮询之间的等待秒数（默认值：10）
• max_wait （可选）：最长等待秒数（默认值：300）

例子：

Generate a video of a sunset over the ocean and save it to /home/user/videos/sunset.mp4

注： 视频总是保存到文件中（对于base64来说太大）。视频URL将在1天后过期。

模型

GLM图像

Z.AI的旗舰图像生成模型，采用混合自回归+扩散架构。

• 最适合：复杂的构图、文字渲染、详细的插图、商业海报
• 质量选项: hd （详细，约20s）， standard （更快，~5-10秒）
• 尺寸范围：每个维度1024-2048px（可被32整除）
• 推荐尺寸: 1280×1280, 1568×1056, 1056×1568, 1472×1088, 1088×1472, 1728×960, 960×1728
• 异步支持：是的

CogView-4-250304

具有快速文本理解功能的通用图像生成。

• 最适合：通用图像生成，快速迭代
• 质量选项: hd, standard
• 尺寸范围：每个维度512-2048px（可被16整除）
• 推荐尺寸: 1024×1024, 768×1344, 864×1152, 1344×768, 1152×864, 1440×720, 720×1440
• 异步支持：没有

______________________________________________________________________

视频模型

CogVideoX-3

Z.AI的旗舰视频生成模型，具有改进的帧稳定性和清晰度。

• 最适合：文本到视频、图像到视频、开始结束帧动画
• 决心：高达4K（3840x2160）
• 持续时间：5或10秒
• 特性：音频生成，30/60 FPS，质量/速度模式
• 价格：0.20美元/视频

Q1视频

1080P输出的高质量视频生成。

• 特性：通用/动漫风格，运动幅度控制

视频2

具有720P输出的快速且经济高效的视频生成。

• 特性：音频生成、运动幅度控制、多图像参考

错误处理

服务器处理各种错误情况：

发展

设置

git clone 
cd z-ai-image-mcp
npm install
cp .env.example .env
# Edit .env with your API key

脚本

npm run build        # Build TypeScript
npm run dev          # Run in development mode
npm test             # Run all tests
npm run test:unit    # Run unit tests only
npm run test:integration  # Run integration tests
npm run test:e2e     # Run E2E tests
npm run test:coverage    # Run tests with coverage
npm run typecheck    # Type check without emit

许可证

麻省理工学院

链接

• Z.AI文件
• MCP文件
• 获取API密钥
• GLM 编程计划