Hunyuan Image Replicate MCP Server

🚀 Hunyuan Image Replicate MCP Server

This is a Model Context Protocol (MCP) server that utilizes the Replicate platform and the Hunyuan Image model to offer image generation capabilities.

✨ Features

Hunyuan Image is an advanced text-to-image foundation model with the following outstanding capabilities:

• Amazing capabilities of Hunyuan Image 2.1 to generate images that convey the sentiment of your text.
• High-quality image generation based on detailed text prompts.
• Support for multiple image sizes and aspect ratios.
• Advanced guidance controls for fine-tuning the results.
• Reproducible generation with seed support.
• Batch generation of up to 4 images at once.

🛠️ Available Tools

generate_image

Use Hunyuan Image via Replicate to generate high-quality images from text prompts.

Parameters:

• prompt (required): A text description of the image to be generated (supports detailed prompts).
• image_size (optional): Image size - one of: 1024x1024, 1152x896, 896x1152, 1216x832, 832x1216, 1344x768, 768x1344, 1536x640, 640x1536 (default: 1024x1024).
• num_outputs (optional): The number of images to generate (1 - 4, default: 1).
• num_inference_steps (optional): The number of denoising steps (1 - 100, default: 25).
• guidance_scale (optional): Controls adherence to the prompt, higher value means stricter (1 - 20, default: 7.5).
• seed (optional): A random seed for reproducible results.

📦 Installation

Prerequisites

1. Replicate API Token: Obtain your API token from Replicate.

   • Sign up for an account at https://replicate.com/.
   • Navigate to your account settings and generate an API token.
   • Keep this token secure as it is required for configuration.

2. Node.js: Make sure you have Node.js installed (version 18 or higher).

Quick Setup (Recommended)

The simplest way to use this server is through npx, which automatically downloads and runs the latest version:

For Claude Desktop App

Add the server to your Claude Desktop configuration file:

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"
      }
    }
  }
}

For Kilo Code MCP Settings

Add it to your MCP settings file at: 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": []
    }
  }
}

Benefits of npx Configuration

✅ Universal Access: Works on any machine with Node.js. ✅ No Local Installation: npx automatically downloads and runs the server. ✅ Always Latest Version: Pulls from the GitHub repository. ✅ Cross-Platform: Compatible with Windows, macOS, and Linux. ✅ Settings Sync: Works wherever you use your MCP client.

Manual Installation (Alternative)

If you prefer to install locally:

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Build the server

   npm run build
   

4. Use absolute path in configuration

   {
     "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"
         }
       }
     }
   }
   

Helper script to get the absolute path:

npm run get-path

💻 Usage Examples

Once configured, you can use the server through your MCP client:

Basic Image Generation

Generate an image of a serene mountain landscape at sunset with a lake reflection

Complex Scene Description

Create a cartoon consisting of four panels, arranged in a 2x2 grid, depicting a chameleon's dilemma with vibrant colors and clean lines

Specific Image Size

Generate a portrait-oriented image of a futuristic cityscape (896x1152)

High-Quality Generation

Generate a photorealistic portrait with 50 inference steps and guidance scale 10

Advanced Parameters

Create a detailed fantasy landscape with seed 12345 for reproducibility and generate 2 variations

📚 API Response Format

The server returns detailed information about the generated images:

✅ Successfully generated 1 image(s) using Hunyuan Image:

📝 **Generation Details:**
• Prompt: "a serene mountain landscape at sunset"
• Image Size: 1024x1024
• Number of Images: 1
• Inference Steps: 25
• Guidance Scale: 7.5
• Seed Used: 1234567890
• Generation Time: 4500ms

🖼️ **Generated Images (1 total, 1 downloaded):**
• Image 1: ./images/hunyuan_image_mountain_landscape_0_2024-01-15T10-30-45.webp (https://replicate.delivery/...)

💾 Images have been downloaded to the local 'images' directory.

🔧 Development

Local Testing

# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

Watch Mode

npm run watch

Run Test Server

npm run test:server

Health Check

npm run health-check

Inspector Tool

npm run inspector

⚙️ Environment Variables

Required

• REPLICATE_API_TOKEN: Your Replicate API token (required for image generation).

Optional

• NODE_ENV: Environment mode (development, production, test) - default: production.
• LOG_LEVEL: Logging level (error, warn, info, debug) - default: info.
• MAX_CONCURRENT_REQUESTS: Maximum concurrent requests (1 - 10) - default: 3.
• REQUEST_TIMEOUT: Request timeout in milliseconds (30000 - 600000) - default: 300000.

🛠️ Troubleshooting

Common Issues

1. "REPLICATE_API_TOKEN environment variable is required"

   • The server will continue running and display this helpful error message.
   • Ensure your Replicate API token is correctly set in the MCP configuration.
   • Verify that the token is valid and starts with 'r8_'.
   • Note: The server no longer crashes when the API token is missing.

2. "Server not showing up in Claude"

   • If using npx configuration, make sure you have Node.js installed (v18+).
   • For manual installation, check that the absolute path is correct.
   • Restart Claude Desktop after making configuration changes.
   • Verify that the JSON configuration syntax is valid.

3. "Generation failed"

   • Check if your Replicate account has sufficient credits or is properly set up for billing.
   • Verify that your API token has the necessary permissions.
   • Try using a simpler prompt to test connectivity.
   • Check if the image size and parameters are valid.

4. "npx command not found"

   • Ensure that Node.js is properly installed.
   • Try running node --version and npm --version to verify the installation.

Server Stability Improvements

✅ Robust Error Handling: The server continues running even without an API token. ✅ Graceful Shutdown: Properly handles SIGINT and SIGTERM signals. ✅ User-Friendly Messages: Provides clear error messages with setup instructions. ✅ No More Crashes: Eliminated process.exit() calls that caused connection drops. ✅ Local Image Storage: Downloads generated images for offline access.

Debug Logging

The server outputs debug information to stderr, which can assist in diagnosing issues:

• Generation progress updates.
• Error messages with helpful instructions.
• API call details.
• Graceful shutdown notifications.

Performance Tips

• Lower num_inference_steps for faster generation (try 15 - 20).
• Cache results using the seed parameter for reproducibility.
• Use appropriate image sizes for your use case.

💰 Pricing

Image generation costs are determined by Replicate's pricing structure. Check Replicate Pricing for current rates. The Hunyuan Image model typically costs around $0.001 - 0.003 per image, depending on the parameters.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests if applicable.
5. Submit a pull request.

🆘 Support

For issues related to:

• This MCP server: Open an issue in this repository.
• Replicate API: Contact Replicate support.
• Hunyuan Image model: Refer to Replicate documentation.

📜 Changelog

v2.0.0 (Latest)

• 🚀 Switched to Replicate: Migrated from fal.ai to Replicate for improved stability and features.
• 🔧 Updated Dependencies: Using the replicate package for API integration.
• ⚙️ Updated Parameters: Adjusted parameters to match Replicate's Hunyuan Image model.
• 📝 Updated Documentation: All documentation now reflects Replicate usage.
• 🖼️ WebP Format: Images are now saved in WebP format for better compression.

v1.1.0

• 🚀 Switched to Hunyuan Image: Migrated from Qwen Image to Hunyuan Image 2.1 for improved image generation.
• 🔧 Updated Dependencies: Using @fal-ai/client for fal.ai integration.
• ⚙️ Enhanced Parameters: Added new parameters like use_reprompt, use_refiner, enable_safety_checker, and num_images.
• 📝 Updated Documentation: All documentation now reflects Hunyuan Image usage.

v1.0.0

• 🎨 Hunyuan Image Integration: Fully implemented the Hunyuan Image model via fal.ai.
• 🔧 Fixed connection drops: Removed process.exit() calls that caused server crashes.
• 🛡️ Improved error handling: The server continues running even without an API key.
• 🌍 Added portability: npx configuration works on any machine.
• 📦 Enhanced stability: Implemented graceful shutdown handlers and null safety checks.
• 💬 Better user experience: Provides clear error messages with setup instructions.
• 🔄 Auto-updating: npx automatically pulls the latest version from GitHub.
• 📁 Local image storage: Downloads generated images to the local directory.

v0.1.1

• Initial fal.ai integration.
• Basic image generation functionality.

v0.1.0

• Initial release with a placeholder implementation.

📚 Additional Resources

• Hunyuan Image Model on Replicate
• Replicate API Documentation
• Model Context Protocol Specification
• MCP SDK Documentation