Jimeng4 MCP Server

即梦AI多模态MCP (jimeng4-mcp)

这是一个基于火山引擎即梦AI的多模态生成服务，完整支持即梦4.0、图生图3.0、文生图3.1/3.0等所有最新模型，可通过MCP协议在Cursor、Claude Desktop等MCP客户端中使用，也可作为独立库调用。支持 macOS、Linux、Windows 及 WSL 环境。

作者: bachstudio
包名: jimeng4-mcp

版本更新

v1.0.0 (首次发布)

• 重大更新: 完整支持即梦AI官方文档中的所有最新模型
• 新增即梦4.0图片生成工具 (jimeng-v40-generate) - 支持文生图、图像编辑及多图组合生成，最多10张输入图，最多15张输出图，支持4K超高清输出
• 新增即梦图生图3.0智能参考工具 (jimeng-i2i-v30) - 支持基于文本指令进行图像编辑
• 新增即梦文生图3.1工具 (jimeng-t2i-v31) - 画面效果呈现升级版，在美感、风格和细节方面显著提升
• 新增即梦文生图3.0工具 (jimeng-t2i-v30) - 文字响应准确度提升版，支持各类艺术字体
• 所有新工具均采用异步任务模式，自动处理任务提交和结果轮询

v1.0.14

• 增强MCP工具定义，确保所有工具在客户端可见
• 优化异步参数处理，默认启用异步模式避免超时
• 增加更详细的视频生成调试信息

v1.0.9-beta.1

• 测试版：增强MCP工具定义，确保所有工具在客户端可见
• 优化异步参数处理，默认启用异步模式避免超时
• 增加更详细的视频生成调试信息
• 修复工具参数传递问题

v1.0.5

• 优化文档结构，为不同平台提供清晰配置说明
• 增加 PowerShell 配置示例
• 提供各平台永久环境变量设置方法
• 添加多平台配置注意事项

v1.0.4

• 优化服务启动和响应返回，现在所有响应均使用标准JSON格式
• 统一错误处理和成功响应的数据结构
• 增强错误信息的可读性和可解析性

核心功能

图像生成系列

• ✅ 即梦4.0图片生成 (jimeng-v40-generate) - 支持文生图、图像编辑及多图组合生成（最多10张输入图，最多15张输出图），支持4K超高清输出
• ✅ 即梦图生图3.0 (jimeng-i2i-v30) - 基于文本指令的智能图像编辑（添加/删除实体、修改风格/色彩/动作/背景等）
• ✅ 即梦文生图3.1 (jimeng-t2i-v31) - 画面效果呈现升级版，在美感、风格精准多样及细节丰富度方面显著提升
• ✅ 即梦文生图3.0 (jimeng-t2i-v30) - 文字响应准确度提升版，支持图文排版和各类艺术字体

视频生成系列

• ✅ 文生视频 - 将文本描述转换为流畅视频 (模型: jimeng_vgfm_t2v_l20)
• ✅ 图生视频 - 将静态图像转换为动态视频 (模型: jimeng_vgfm_i2v_l20)

技术特性

• ✅ 多平台支持 - 支持 macOS、Linux、Windows 及 WSL 环境
• 🛠️ 完整TypeScript类型定义和错误处理
• 🔄 支持异步任务处理和状态追踪
• 🎛️ 自定义参数控制 (尺寸、比例、风格、种子等)

系统架构

以下流程图展示了即梦AI多模态MCP的工作流程和系统架构：

graph LR
    A[用户输入] --> B[MCP协议解析]
    B --> C{工具选择}
    C -->|图像生成| D[generate-image]
    C -->|视频生成| E[generate-video]
    C -->|提交视频任务| F[submit-video-task]
    C -->|查询视频任务| G[get-video-task]
    
    D --> H[JimengClient]
    E --> H
    F --> H
    G --> H
    
    H --> I{API调用}
    I -->|图生成| J[火山引擎即梦AI图像生成API]
    I -->|视频生成| K[火山引擎即梦AI视频生成API]
    I -->|任务查询| L[火山引擎即梦AI任务状态API]
    
    J --> M[生成结果]
    K --> M
    L --> M
    
    M --> N[返回MCP响应]
    N --> O[用户展示]

可用MCP工具

即梦AI新版图像生成工具（推荐使用）

视频生成工具

传统工具（向后兼容）

快速开始

安装

所有平台（macOS/Linux/Windows）：

# NPM全局安装
npm install -g jimeng4-mcp

# 或本地安装（开发）
git clone <your-repo-url>
cd jimeng4-mcp
npm install
npm run build

环境变量配置

在使用前，需设置火山引擎即梦AI服务的访问密钥：

macOS/Linux

# 设置环境变量
export JIMENG_ACCESS_KEY=你的火山引擎访问密钥
export JIMENG_SECRET_KEY=你的火山引擎密钥

# 或创建.env文件
echo "JIMENG_ACCESS_KEY=你的火山引擎访问密钥" > .env
echo "JIMENG_SECRET_KEY=你的火山引擎密钥" >> .env

# 永久设置环境变量（添加到 .bashrc 或 .zshrc）
echo 'export JIMENG_ACCESS_KEY="你的火山引擎访问密钥"' >> ~/.bashrc
echo 'export JIMENG_SECRET_KEY="你的火山引擎密钥"' >> ~/.bashrc
source ~/.bashrc

WSL (Windows Subsystem for Linux)

# 设置环境变量
export JIMENG_ACCESS_KEY=你的火山引擎访问密钥
export JIMENG_SECRET_KEY=你的火山引擎密钥

# 或创建.env文件
echo "JIMENG_ACCESS_KEY=你的火山引擎访问密钥" > .env
echo "JIMENG_SECRET_KEY=你的火山引擎密钥" >> .env

# 永久设置环境变量（添加到 .bashrc）
echo 'export JIMENG_ACCESS_KEY="你的火山引擎访问密钥"' >> ~/.bashrc
echo 'export JIMENG_SECRET_KEY="你的火山引擎密钥"' >> ~/.bashrc
source ~/.bashrc

Windows

命令提示符 (CMD):

:: 临时设置环境变量（当前会话有效）
set JIMENG_ACCESS_KEY=你的火山引擎访问密钥
set JIMENG_SECRET_KEY=你的火山引擎密钥

:: 创建.env文件
echo JIMENG_ACCESS_KEY=你的火山引擎访问密钥 > .env
echo JIMENG_SECRET_KEY=你的火山引擎密钥 >> .env

:: 永久设置环境变量（管理员命令提示符）
setx JIMENG_ACCESS_KEY "你的火山引擎访问密钥"
setx JIMENG_SECRET_KEY "你的火山引擎密钥"

PowerShell:

# 临时设置环境变量（当前会话有效）
$env:JIMENG_ACCESS_KEY = "你的火山引擎访问密钥"
$env:JIMENG_SECRET_KEY = "你的火山引擎密钥"

# 创建.env文件
"JIMENG_ACCESS_KEY=你的火山引擎访问密钥" | Out-File -FilePath .env -Encoding ASCII
"JIMENG_SECRET_KEY=你的火山引擎密钥" | Out-File -FilePath .env -Encoding ASCII -Append

# 永久设置环境变量（管理员PowerShell）
[Environment]::SetEnvironmentVariable("JIMENG_ACCESS_KEY", "你的火山引擎访问密钥", "User")
[Environment]::SetEnvironmentVariable("JIMENG_SECRET_KEY", "你的火山引擎密钥", "User")

发布与版本管理

项目包含一个 publish.sh 脚本，用于简化版本发布和管理的流程。

使用方法

在项目根目录下运行脚本：

./publish.sh

脚本会提供一个菜单，引导你完成不同操作。

功能选项

1. 发布新版本 (选项 1-5):
   • patch: 用于修复错误 (例如 1.0.4 -> 1.0.5)。
   • minor: 用于添加向后兼容的功能 (例如 1.0.4 -> 1.1.0)。
   • major: 用于不向后兼容的重大更改 (例如 1.0.4 -> 2.0.0)。
   • beta: 创建或递增一个测试版本 (例如 1.0.4 -> 1.0.5-beta.0 或 `