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文檔