yooztech-mcp-minimax-t2i 0.0.4

MCP server for MiniMax image generation (text-to-image and image-to-image)

yooztech_mcp_minimax_t2i —— MiniMax 图片生成 MCP 工具

基于 MCP (Model Context Protocol) 的 MiniMax 图片生成服务，提供文生图（text-to-image）与图生图（image-to-image）两种核心功能。

功能概述

• text_to_image(prompt, ...): 根据文本描述生成图片，并在同一次调用内用 API Key 鉴权下载并保存到本地（接口返回的 URL 需 Bearer 鉴权，直接访问会 401，有效期 24 小时）
• image_to_image(prompt, subject_reference, ...): 结合参考图生成图片，并在同一次调用内完成鉴权下载与本地保存

在 Cursor 中配置

需要在 MCP Server 配置中设置环境变量 MINIMAX_API_KEY：

{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "yooztech_mcp_minimax_t2i",
      "args": [],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 uvx 方式：

{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "uvx",
      "args": ["yooztech_mcp_minimax_t2i"],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}

API Key 获取

请访问 MiniMax 开放平台 注册账号并获取 API Key。

工具详解

1. text_to_image - 文生图

根据详尽的文本描述（prompt），直接生成与之匹配的图片。

参数：

• prompt (必填): 图片描述文本，建议详细描述场景、主体、风格等
• model (可选): 使用的模型，默认 "image-01"
• aspect_ratio (可选): 图片宽高比，默认 "16:9"
  • 可选值：1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9（21:9 仅 image-01）
• output_dir (可选): 保存目录，默认当前目录
• filename_prefix (可选): 本地文件名前缀，默认 output，生成文件为 {prefix}-0.jpeg 等

返回：

• success: 生成与下载是否全部成功
• saved_files: 已保存的本地文件路径列表
• download_errors: 若有下载失败则列出原因
• images: 接口返回的图片 URL（需鉴权访问，日常以 saved_files 为准）
• status_code / status_msg: 接口状态
• model / aspect_ratio: 使用的模型与宽高比

使用示例：

{
  "tool": "text_to_image",
  "args": {
    "prompt": "men Dressing in white t shirt, full-body stand front view image :25, outdoor, Venice beach sign, full-body image, Los Angeles, Fashion photography of 90s, documentary, Film grain, photorealistic",
    "aspect_ratio": "16:9"
  }
}

2. image_to_image - 图生图

此功能允许提供一张或多张包含清晰主体的参考图（支持网络图片链接），并结合 prompt 描述，生成一张保留了主体特征的新图片。

参数：

• prompt (必填): 图片描述文本，描述希望生成的场景
• subject_reference (必填): 参考图列表，每项包含：
  • type: 参考图类型，目前仅支持 "character"（角色）
  • image_file: 参考图 URL（支持网络图片链接）
• model (可选): 使用的模型，默认 "image-01"
• aspect_ratio (可选): 图片宽高比，默认 "16:9"
• output_dir / filename_prefix (可选): 同 text_to_image

返回：

• success: 生成与下载是否全部成功
• saved_files: 已保存的本地文件路径列表
• images: 生成的图片 URL 列表
• model / aspect_ratio: 使用的模型与宽高比

使用示例：

{
  "tool": "image_to_image",
  "args": {
    "prompt": "女孩在图书馆的窗户前，看向远方",
    "subject_reference": [
      {
        "type": "character",
        "image_file": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/xxx.jpg"
      }
    ]
  }
}

完整使用流程

1. 在 Cursor 配置中设置 MINIMAX_API_KEY 环境变量
2. 调用 text_to_image 或 image_to_image；成功时在同一次响应中返回 saved_files（已带 Bearer 鉴权下载到本地）

MiniMax 返回的图片 URL 需要带 Bearer Token 才能访问；本工具在生成成功后立即用同一 API Key 下载并写入 output_dir，无需再分步调用。

错误处理

所有工具在失败时会返回包含错误信息的字典，包含以下字段：

• success: 是否成功
• error: 错误类型
• message: 错误详情

依赖

• Python >= 3.10
• mcp >= 1.2.0
• httpx >= 0.27.0

许可证

MIT (见 LICENSE)