Hunyuan Image Replicate MCP Server

🚀 混元图像复制MCP服务器

这是一个模型上下文协议（MCP）服务器，可通过Replicate平台使用混元图像模型提供图像生成功能。

✨ 主要特性

混元图像是一款先进的文生图基础模型，具备以下出色能力：

• 强大的图像表达能力：混元图像2.1能够生成精准传达文本情感的图像。
• 高质量图像生成：根据详细的文本提示生成高质量图像。
• 多尺寸和宽高比支持：支持多种图像尺寸和宽高比。
• 高级引导控制：可对生成结果进行精细调整。
• 可复现的生成：支持使用种子参数实现可复现的图像生成。
• 批量生成：一次最多可生成4张图像。

📦 安装指南

前提条件

1. Replicate API令牌：从Replicate获取API令牌。
   • 在https://replicate.com/注册账户。
   • 进入账户设置并生成API令牌。
   • 请妥善保管此令牌，后续配置需要使用。
2. Node.js：确保已安装Node.js（版本18或更高）。

快速设置（推荐）

使用此服务器的最简单方法是通过npx，它会自动下载并运行最新版本：

对于Claude桌面应用

将服务器添加到Claude桌面配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "hunyuan-image": {
            "command": "npx",
            "args": [
                "-y",
                "https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git"
            ],
            "env": {
                "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
            }
        }
    }
}

对于Kilo Code MCP设置

添加到MCP设置文件中： C:\Users\[username]\AppData\Roaming\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json

{
    "mcpServers": {
        "hunyuan-image": {
            "command": "npx",
            "args": [
                "-y",
                "https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git"
            ],
            "env": {
                "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
            },
            "disabled": false,
            "alwaysAllow": []
        }
    }
}

npx配置的优势

✅ 通用访问：在任何安装了Node.js的机器上均可使用。 ✅ 无需本地安装：npx会自动下载并运行。 ✅ 始终使用最新版本：从GitHub仓库拉取最新版本。 ✅ 跨平台兼容：支持Windows、macOS和Linux。 ✅ 设置同步：在所有使用MCP客户端的地方均可生效。

手动安装（可选）

如果您希望进行本地安装：

1. 克隆仓库

git clone https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git
cd hunyuan-image-replicate-mcp-server

2. 安装依赖项

npm install

3. 构建服务器

npm run build

4. 在配置中使用绝对路径

{
    "mcpServers": {
        "hunyuan-image": {
            "command": "node",
            "args": ["/absolute/path/to/hunyuan-image-replicate-mcp-server/build/index.js"],
            "env": {
                "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
            }
        }
    }
}

获取绝对路径的辅助脚本：

npm run get-path

💻 使用示例

配置完成后，您可以通过MCP客户端使用该服务器：

基础用法

生成一张日落时分宁静的山区风景图，带有湖面倒影

高级用法

复杂场景描述

创建一个由四个面板组成的卡通画，以2x2网格排列，描绘一只变色龙的困境，色彩鲜艳，线条简洁

特定图像尺寸

生成一张竖版的未来城市风景图（896x1152）

高质量生成

使用50个去噪步骤和引导比例10生成一张逼真的肖像画

高级参数

创建一个详细的奇幻风景图，使用种子12345以确保可复现，并生成2个变体

📚 详细文档

可用工具

generate_image

通过Replicate使用混元图像从文本提示生成高质量图像。

参数：

API响应格式

服务器会返回有关生成图像的详细信息：

✅ 成功使用混元图像生成1张图像：

📝 **生成详情**：
• 提示："日落时分宁静的山区风景"
• 图像尺寸：1024x1024
• 图像数量：1
• 推理步骤：25
• 引导比例：7.5
• 使用的种子：1234567890
• 生成时间：4500ms

🖼️ **生成的图像（共1张，已下载1张）**：
• 图像1：./images/hunyuan_image_mountain_landscape_0_2024-01-15T10-30-45.webp (https://replicate.delivery/...)

💾 图像已下载到本地的'images'目录。

🔧 技术细节

开发

本地测试

# 直接测试服务器
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

监听模式

npm run watch

运行测试服务器

npm run test:server

健康检查

npm run health-check

检查工具

npm run inspector

环境变量

必需

• REPLICATE_API_TOKEN：您的Replicate API令牌（图像生成必需）

可选

• NODE_ENV：环境模式（development、production、test） - 默认：production
• LOG_LEVEL：日志级别（error、warn、info、debug） - 默认：info
• MAX_CONCURRENT_REQUESTS：最大并发请求数（1 - 10） - 默认：3
• REQUEST_TIMEOUT：请求超时时间（毫秒）（30000 - 600000） - 默认：300000

故障排除

常见问题

1. "REPLICATE_API_TOKEN环境变量是必需的"
   • 服务器会继续运行并显示此有用的错误消息。
   • 确保您的Replicate API令牌已正确设置在MCP配置中。
   • 验证令牌是否有效且以'r8_'开头。
   • 注意：当API令牌缺失时，服务器不再崩溃。
2. "服务器未在Claude中显示"
   • 如果使用npx配置，请确保已安装Node.js（v18+）。
   • 对于手动安装，检查绝对路径是否正确。
   • 配置更改后重启Claude桌面应用。
   • 验证JSON配置语法是否有效。
3. "生成失败"
   • 检查您的Replicate账户是否有足够的信用额度或已设置计费方式。
   • 验证您的API令牌是否具有必要的权限。
   • 尝试使用更简单的提示来测试连接。
   • 检查图像尺寸和参数是否有效。
4. "未找到npx命令"
   • 确保已正确安装Node.js。
   • 尝试运行node --version和npm --version以验证安装情况。

服务器稳定性改进

✅ 强大的错误处理：即使没有API令牌，服务器也能继续运行。 ✅ 优雅关闭：正确处理SIGINT和SIGTERM信号。 ✅ 用户友好消息：提供清晰的错误消息和设置说明。 ✅ 不再崩溃：消除了导致连接中断的process.exit()调用。 ✅ 本地图像存储：下载生成的图像以供离线访问。

调试日志

服务器会将调试信息输出到stderr，有助于诊断问题：

• 生成进度更新
• 带有有用说明的错误消息
• API调用详情
• 优雅关闭通知

性能提示

• 降低num_inference_steps以加快生成速度（可尝试15 - 20）。
• 使用seed参数缓存结果以实现可复现性。
• 根据使用场景选择合适的图像尺寸。

定价

图像生成成本由Replicate的定价结构决定。请查看Replicate定价以获取当前费率。混元图像模型通常每张图像的成本约为0.001 - 0.003美元，具体取决于参数。

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 提交拉取请求

支持

• 此MCP服务器相关问题：在此仓库中创建问题。
• Replicate API相关问题：联系Replicate支持。
• 混元图像模型相关问题：参考Replicate文档。

更新日志

v2.0.0（最新）

• 🚀 切换到Replicate：从fal.ai迁移到Replicate，以提高稳定性和功能。
• 🔧 更新依赖项：使用replicate包进行API集成。
• ⚙️ 更新参数：调整参数以匹配Replicate的混元图像模型。
• 📝 更新文档：所有文档均反映了Replicate的使用情况。
• 🖼️ WebP格式：图像现在以WebP格式保存，以实现更好的压缩。

v1.1.0

• 🚀 切换到混元图像：从通义千问图像迁移到混元图像2.1，以改进图像生成效果。
• 🔧 更新依赖项：使用@fal-ai/client进行fal.ai集成。
• ⚙️ 增强参数：添加了新参数，如use_reprompt、use_refiner、enable_safety_checker和num_images。
• 📝 更新文档：所有文档均反映了混元图像的使用情况。

v1.0.0

• 🎨 混元图像集成：通过fal.ai全面实现混元图像模型。
• 🔧 修复连接中断问题：消除了导致服务器崩溃的process.exit()调用。
• 🛡️ 改进错误处理：即使没有API密钥，服务器也能继续运行。
• 🌍 增加可移植性：npx配置可在任何机器上使用。
• 📦 增强稳定性：添加了优雅关闭处理程序和空值安全检查。
• 💬 改善用户体验：提供清晰的错误消息和设置说明。
• 🔄 自动更新：npx会自动从GitHub拉取最新版本。
• 📁 本地图像存储：将生成的图像下载到本地目录。

v0.1.1

• 初始fal.ai集成
• 基本图像生成功能

v0.1.0

• 初始版本，包含占位实现

额外资源

• Replicate上的混元图像模型
• Replicate API文档
• 模型上下文协议规范
• MCP SDK文档