ImaginePro MCP Server

ImaginePro MCP 服务器

一个快速且功能强大的MCP（模型上下文协议）服务器，它带来 ImaginePro 为您的AI助手（如Claude）提供AI图像和视频生成能力，使其能够通过自然语言实现无缝的创意内容生成。

What's New in v1.1.0 🎉

重大改进:

• 自动完成等待中所有生成工具现在都会自动等待任务完成后再返回结果
• 实时进度更新在图像和视频创建过程中实时查看生成进度
• 固定URL映射修正了图像/视频URL字段映射，以确保可靠访问生成的内容
• 增强响应数据所有工具现在都返回状态和进度信息，以便更好地进行跟踪
• 改进的错误处理更具有描述性的错误消息，采用标准化格式

重大变更无 - 所有更改均向后兼容！

目录

• 为什么选择ImaginePro MCP？
• 特性/特点
• 快速入门
• 安装
• 工具参考
• 使用示例
• 故障排除
• 贡献；做出贡献

为什么选择ImaginePro MCP？

• 🚀 快速且轻量优化用于快速生成图像和视频
• 🎨 全面的支持文本到图像生成、视频生成、图像超分辨率、变体生成和图像修复
• 🔧 轻松集成与Claude Desktop、Claude Code以及任何MCP兼容工具协同工作
• 🎯 准备就绪，可投入生产使用TypeScript构建，具备全面的错误处理和强大的API集成
• 📦 简单设置使用 npx 或 npm 在几秒内安装

特点/特性

• 文本到图像生成根据文本描述创建惊艳的AI图像
• 多模态生成结合文本和图像进行高级生成（Gemini）
• 视频生成从起始帧和结束帧创建流畅的视频动画
• 图像超分辨率技术（或图像放大）提高图像分辨率和质量
• 镜像变体生成现有图像的替代版本
• 图像重绘使用相同的提示重新生成图像
• 图像修复（或内容填充）使用遮罩编辑图像的特定区域
• 状态追踪实时检查生成任务的进度

快速入门

先决条件

• Node.js 版本 >= 18.0.0
• 一 想象一下，ImaginePro API密钥 （免费注册）
• Claude Desktop、Claude Code 或任何MCP兼容工具

安装

ImaginePro MCP服务器可以根据您的工具和偏好以多种方式安装。

选项1：使用npx快速安装（推荐）

最简单的方式开始使用——无需安装！

Claude Desktop（中文可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”，但通常直接保留原名以体现品牌特色）

添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

克劳德·科德

快速安装 （推荐）：

# Set your API key first
export IMAGINEPRO_API_KEY="sk-your-api-key-here"

# Add the server with the API key
claude mcp add-json imaginepro '{"command":"npx","args":["-y","imaginepro-mcp-server"],"env":{"IMAGINEPRO_API_KEY":"'"$IMAGINEPRO_API_KEY"'"}}' -s local

将您的API密钥设为永久：

echo 'export IMAGINEPRO_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Alternative Installation Methods

手动配置：

编辑您的MCP设置：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

使用Shell环境变量：

在没有（某物/某功能）的情况下进行配置 env 区块：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"]
    }
  }
}

然后在你的shell中导出：

export IMAGINEPRO_API_KEY="sk-your-api-key-here"

注MCP配置 env 块级变量优先于shell环境变量。

其他MCP工具

对于Cursor、Goose或LM Studio等工具，请使用类似的配置：

{
  "imaginepro": {
    "command": "npx",
    "args": ["-y", "imaginepro-mcp-server"],
    "env": {
      "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
    }
  }
}

Option 2: Global Installation

使用 npm 全局安装：

npm install -g imaginepro-mcp-server

然后进行配置：

{
  "mcpServers": {
    "imaginepro": {
      "command": "imaginepro-mcp-server",
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Option 3: Local Development

对于开发或定制：

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

然后进行配置：

{
  "mcpServers": {
    "imaginepro": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

《科德克斯》（Codex）

添加到 ~/.codex/config.toml：

[mcp_servers.imaginepro]
command = "npx"
args = ["-y", "imaginepro-mcp-server"]

[mcp_servers.imaginepro.env]
IMAGINEPRO_API_KEY = "sk-your-api-key-here"

获取您的API密钥

1. 在（某处）注册 imaginepro.ai（可译为“想象创造AI”或根据具体语境调整，但直接保留原英文域名形式也是常见的）
2. 导航至您的账户设置
3. 生成一个API密钥
4. 复制并在上面的配置中使用它

Configuration for Other MCP Clients

ImaginePro MCP服务器可与许多流行的AI开发工具协同工作。以下是针对每个客户端的具体配置说明。

光标

添加到你的光标设置中（.cursor/config.json 或通过设置用户界面（Settings UI）：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

风帆冲浪（代码区）

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Gemini CLI、VS Code、Goose、LM Studio、Warp Terminal、Amp

对于大多数其他兼容MCP的工具，请使用标准配置：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

注一些工具可能会使用略有不同的配置键（例如。， mcp.servers 对于 VS Code， amp.mcpServers （用于Amp）。请参阅您工具的MCP文档。

工具参考

Available Tools (8 total)

ImaginePro MCP服务器提供了8款强大的工具，用于AI图像和视频生成。所有工具都会返回包含生成内容URL的结构化响应。

核心生成工具

generate-image

利用先进的文本到图像模型，根据文本描述生成AI图像。

参数：

• prompt （字符串，必填）：要生成的图像的详细描述
• ref (字符串，可选)：用于追踪的参考ID
• webhookOverride （字符串，可选）：用于异步通知的Webhook URL

返回值：

• messageId生成图像的唯一标识符
• imageUrl生成图像的直接URL
• status生成状态（已完成、失败等）
• progress完成百分比（0-100）

注此工具现在会等待图像处理完成后再返回（通常需要30-60秒）。

示例用法：

Generate a photorealistic image of a serene mountain lake at sunrise, with mist rising from the water and pine trees reflected in the still surface

gemini-imagine

使用多模态输入生成图像，将文本提示与现有图像相结合。

参数：

• contents （数组，必需）：包含类型（'text' 或 'image'）、文本和 URL 的内容项数组
• model (字符串，可选)：要使用的模型（默认：gemini-2.5-flash-image-preview）
• ref (字符串，可选)：用于追踪的参考ID
• webhookOverride （字符串，可选）：Webhook URL

返回值：

• messageId唯一标识符
• imageUrl生成图像的直接URL
• status生成状态
• progress完成百分比

注自动等待完成后再返回。

示例用法：

Use this image [cat.jpg] and make the cat wearing a royal crown and sitting on a throne

generate-video

创建在两个帧之间过渡的平滑视频动画。

参数：

• prompt （字符串，必填）：视频过渡/动画的描述
• startFrameUrl （字符串，必填）：起始帧图像的URL
• endFrameUrl （字符串，必填）：结束帧图像的URL
• ref （字符串，可选）：参考ID
• webhookOverride (字符串，可选)：Webhook URL

返回值：

• messageId唯一标识符
• videoUrl生成视频的直接链接
• status生成状态
• progress完成百分比

注视频生成需要更长时间（通常为1-3分钟）。工具会等待其完成。

示例用法：

Create a smooth morphing video between sunset.jpg and night.jpg with a natural day-to-night transition

图像增强工具

upscale-image

使用AI超分辨率技术提升图像分辨率和质量。

参数：

• messageId (字符串，必填)：要放大处理的图像的消息ID
• ref (字符串，可选)：参考ID
• webhookOverride （字符串，可选）：Webhook URL

返回值：

• messageId新消息标识符
• imageUrl放大后的图像URL
• status生成状态
• progress完成百分比

注等待上采样完成后再返回。

示例用法：

Upscale the image with message ID abc123 to higher resolution

create-variant

为现有图像生成具有不同风格或变化的替代版本。

参数：

• messageId (字符串，必填)：基础镜像的消息ID
• ref （字符串，可选）：参考ID
• webhookOverride （字符串，可选）：Webhook URL

返回值：

• messageId新的消息标识符
• imageUrl变体图像的URL
• status生成状态
• progress完成百分比

注等待变体生成完成后再返回。

示例用法：

Create a variant of the image abc123

reroll-image

使用相同的原始提示重新生成一张图像。

参数：

• messageId (字符串，必填)：要重新抽取的图片的消息ID
• ref （字符串，可选）：参考ID
• webhookOverride (字符串，可选)：Webhook URL

返回值：

• messageId新的消息标识符
• imageUrl新图片的URL
• status世代状态
• progress完成百分比

注等待再生过程完成后再返回。

示例用法：

Reroll the image abc123 to get a different result

图像编辑工具

inpaint-image

通过提供一个指示需要修改区域的掩膜，来编辑图像的特定区域。

参数：

• messageId （字符串，必填）：基础镜像的消息ID
• maskUrl （字符串，必填）：遮罩图像的URL（白色区域将被编辑）
• prompt （字符串，必填）：描述在遮罩区域中要生成的内容
• ref （字符串，可选）：参考ID
• webhookOverride (字符串，可选)：Webhook URL

返回值：

• messageId新的消息标识符
• imageUrl修复后的图像URL
• status代际状态
• progress完成百分比

注等待修复完成后再返回。

示例用法：

Inpaint the image abc123 using mask at mask.png and add a rainbow in the sky

实用工具

fetch-status

检查任何生成任务的实时状态和进度。

参数：

• messageId (字符串，必需): 用于检查状态的消息ID

返回值：

• status当前状态（待处理、处理中、已完成、已失败）
• progress进度百分比（0-100）
• imageUrl生成的图像URL（准备就绪时）
• videoUrl生成视频的URL（完成后）

示例用法：

Check the status of generation task abc123

使用示例

以下是使用ImaginePro MCP服务器展示不同使用场景的实际示例。

示例1：简单图像生成

只需用自然语言描述你的需求：

Generate an image of a cozy coffee shop interior with warm lighting, wooden furniture,
and customers reading books. Make it photorealistic.

助手将自动：

1. 呼叫 generate-image 在您的敦促下
2. 返回图片URL和消息ID
3. 显示结果

示例2：多模态图像编辑

将现有图像与文字描述相结合：

I have this image of a cat at cat.jpg. Can you make it wearing a wizard hat
and holding a magic wand, maintaining the same artistic style?

用途 gemini-imagine 处理图像以及您的修改请求。

示例3：视频生成工作流程

创建流畅的视频过渡效果：

I have two images: sunset-beach.jpg and night-beach.jpg.
Create a 5-second video showing the smooth transition from day to night.

通话 generate-video 在帧之间创建动画过渡效果。

示例4：图像增强处理流程

图像优化的完整工作流程：

1. Generate an image of a fantasy castle
2. Create 3 variants to see different options
3. Upscale the best variant to higher resolution
4. Use inpainting to add dragons flying in the sky

这展示了如何将多个工具串联起来，以实现一个完整的创意工作流程。

示例5：异步状态跟踪

监控长时间运行的生成过程：

Check the status of my video generation task abc123

用途 fetch-status 监控异步操作的进度。

Advanced Configuration

环境变量

配置文件

您可以使用JSON配置文件来替代环境变量：

文件位置 （按顺序核对）：

1. ~/.imaginepro/config.json (全球)
2. ./.imaginepro.json （项目特定的）

示例 (~/.imaginepro/config.json):

{
  "apiKey": "sk-your-api-key-here",
  "baseUrl": "https://api.imaginepro.ai",
  "timeout": 300000
}

优先权环境变量 > 配置文件 > 默认值

自定义超时示例

对于视频生成或大批量处理：

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key",
        "IMAGINEPRO_TIMEOUT": "600000"
      }
    }
  }
}

Development Guide

先决条件

• Node.js 版本 >= 18.0.0
• npm 或 yarn
• TypeScript 知识
• 一个用于测试的ImaginePro API密钥

设置

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

命令

使用Claude桌面版进行测试

将你的配置指向本地构建：

{
  "mcpServers": {
    "imaginepro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-test-key"
      }
    }
  }
}

故障排除

Common Issues & Solutions

常见问题

“IMAGINEPRO_API_KEY”环境变量是必需的

原因服务器找不到您的API密钥。

解决方案：

1. 确保您的API密钥已在MCP配置中设置：

   "env": {
     "IMAGINEPRO_API_KEY": "sk-your-actual-key"
   }

1. 或者在开始之前在你的shell中导出它：

   export IMAGINEPRO_API_KEY="sk-your-api-key"

1. 更改配置后，请重启您的MCP客户端（如Claude Desktop等）

“Failed to generate image”或API错误

可能的原因及解决方案：

• 无效的API密钥验证您的密钥在 imaginepro.ai（可译为“想象创造人工智能平台”或根据具体语境调整为更贴切的名称，但直接音译加意译结合可为“想象创造AI”）
• 学分不足检查您的账户余额
• 网络问题检查互联网连接和防火墙设置
• 速率限制等一会儿再试
• 无效参数检查图片URL是否可访问且提示信息是否有效

“模块未找到”或导入错误

用于npm包安装：

npm install -g imaginepro-mcp-server

用于本地开发：

cd imaginepro-mcp-server
npm install
npm run build

服务器无响应

1. 检查服务器是否确实在运行（查看日志中的启动消息）
2. 验证您的MCP配置中的命令路径是否正确
3. 确保已安装 Node.js 18.0.0 或更高版本： node --version
4. 检查MCP客户端日志以获取详细的错误信息

“命令未找到：imaginepro-mcp”

这种情况发生在使用全局安装时，但二进制文件不在 PATH 环境变量中。

解决方案使用 npx 代替：

{
  "command": "npx",
  "args": ["-y", "imaginepro-mcp-server"]
}

“spawn node ENOENT” 或 “Failed to connect”（使用 nvm 的 Claude 代码）

原因如果你正在使用nvm（Node版本管理器），Claude Code无法找到 node 无法执行，因为它没有继承你 shell 的 PATH。

日志中的错误: spawn node /path/to/dist/index.js ENOENT

解决方案在你的配置中使用节点的完整路径：

1. 找到你的节点路径：

   which node
   # Example output: /Users/username/.nvm/versions/node/v22.19.0/bin/node

1. 更新您的MCP配置以使用完整路径：

   {
     "mcpServers": {
       "imaginepro": {
         "command": "/Users/username/.nvm/versions/node/v22.19.0/bin/node",
         "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
         "env": {
           "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
         }
       }
     }
   }

替代方案如果使用npx来调用已发布的npm包，这个问题就不会出现，因为npx会自动处理node可执行文件。

寻求帮助

如果您仍然遇到问题：

1. 检查日志大多数MCP客户端提供详细的日志
2. 审查示例查看 使用示例 部分；章节
3. 打开一个问题（或：提交一个问题）：
4. 联系支持团队： ImaginePro 支持服务

贡献；做出贡献

How to Contribute

我们欢迎各种贡献！无论是错误报告、功能请求、文档改进，还是代码贡献。

快速入门

1. 克隆并复制仓库
2. 创建一个特性分支： git checkout -b feature/amazing-feature
3. 进行你的更改并测试它们
4. 提交： git commit -m 'Add amazing feature'
5. 推送： git push origin feature/amazing-feature
6. 提交一个拉取请求

指南；指导方针

• 遵循TypeScript的最佳实践
• 使用清晰、描述性的提交信息
• 根据需要更新文档
• 在提交前，请使用 Claude 桌面版进行测试

报告问题

包括：

• 您的环境（操作系统、Node.js版本、MCP客户端）
• 重现步骤
• 预期行为与实际行为
• 错误信息和日志

支持与链接

• ImaginePro API: imaginepro.ai（可译为“想象创造人工智能平台”或根据具体语境简化为“想象AI平台”） | 支持
• GitHub Issues（在GitHub上用于讨论和跟踪问题的功能板块）： 报告错误或请求功能
• 文档： 克劳德·科德 | MCP协议

许可证

MIT 许可证 - 请参阅 许可证 文件中包含详细信息。

______________________________________________________________________

构建于 模型上下文协议 | 由...提供支持/驱动 想象一下，Pro AI（或“专业AI”，具体翻译取决于上下文和品牌定位）