hunyuan-image-fal-mcp-server by PierrunoYT - MCP Server

Hunyuan Image fal.ai MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Hunyuan Image model via the fal.ai platform.

Features

Hunyuan Image is an advanced text-to-image foundation model that excels at:

Amazing capabilities of hunyuan image 2.1 to generate images that express the feelings of your text
High-quality image generation from detailed text prompts
Multiple image sizes and aspect ratios support
Advanced guidance controls for fine-tuning results
Prompt enhancement for potentially better results
Safety checking for content filtering

Available Tools

`generate_image`

Generate high-quality images from text prompts using Hunyuan Image via fal.ai.

Parameters:

prompt (required): Text description of the image to generate (supports detailed prompts)
negative_prompt (optional): Negative prompt to guide the image generation away from certain concepts (default: "")
image_size (optional): Image size/aspect ratio - one of: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9 (default: square_hd)
num_images (optional): Number of images to generate (1-4, default: 1)
num_inference_steps (optional): Number of denoising steps (1-50, default: 28)
guidance_scale (optional): Controls adherence to prompt, higher = stricter (1-20, default: 3.5)
seed (optional): Random seed for reproducible results
use_reprompt (optional): Enable prompt enhancement for better results (default: true)
use_refiner (optional): Enable refiner model for improved quality (default: false)
enable_safety_checker (optional): Enable safety checker (default: true)

Installation

Prerequisites

fal.ai API Key: Get your API key from fal.ai
- Sign up for an account at https://fal.ai/
- Navigate to your dashboard and copy your API key
- Keep this key secure as you'll need it for configuration
Node.js: Ensure you have Node.js installed (version 18 or higher)

Quick Setup (Recommended)

The easiest 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-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your_fal_key_here"
      }
    }
  }
}

For Kilo Code MCP Settings

Add 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-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your_fal_key_here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Benefits of npx Configuration

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

Manual Installation (Alternative)

If you prefer to install locally:

Clone the repository

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

Install dependencies
```
npm install
```
Build the server
```
npm run build
```

Use absolute path in configuration

{
  "mcpServers": {
    "hunyuan-image": {
      "command": "node",
      "args": ["/absolute/path/to/hunyuan-image-fal-mcp-server/build/index.js"],
      "env": {
        "FAL_KEY": "your_fal_key_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 Text Rendering

Create a vintage poster with the text "Welcome to AI Art" in ornate lettering, art deco style

Specific Image Size

Generate a portrait-oriented image of a futuristic cityscape (1024x768)

High-Quality Generation

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

Advanced Parameters

Create a detailed fantasy landscape with negative prompt "blurry, low quality" and seed 12345 for reproducibility

API Response Format

The server returns detailed information about generated images:

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

📝 **Generation Details:**
• Prompt: "a serene mountain landscape at sunset"
• Negative Prompt: "None"
• Image Size: square_hd
• Number of Images: 1
• Inference Steps: 28
• Guidance Scale: 3.5
• Seed Used: 1234567890
• Use Reprompt: true
• Use Refiner: false
• Safety Checker: true
• Generation Time: 4500ms

🖼️ **Generated Images (1 total, 1 downloaded):**
• Image 1: ./images/hunyuan_image_mountain_landscape_0_2024-01-15T10-30-45.png (https://v3.fal.media/files/...)

💾 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

FAL_KEY: Your fal.ai API key (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

"FAL_KEY environment variable is required"
- The server will continue running and show this helpful error message
- Ensure your fal.ai API key is properly set in the MCP configuration
- Verify the key is valid and has sufficient credits
- Note: The server no longer crashes when the API key is missing
"Server not showing up in Claude"
- If using npx configuration, ensure you have Node.js installed (v18+)
- For manual installation, check that the absolute path is correct
- Restart Claude Desktop after configuration changes
- Verify the JSON configuration syntax is valid
"Generation failed"
- Check your fal.ai account has sufficient credits
- Verify your API key has the necessary permissions
- Try with a simpler prompt to test connectivity
- Check if the image size and parameters are valid
"npx command not found"
- Ensure Node.js is properly installed
- Try running node --version and npm --version to verify installation

Server Stability Improvements

✅ Robust Error Handling: Server continues running even without API key ✅ Graceful Shutdown: Proper handling of SIGINT and SIGTERM signals ✅ User-Friendly Messages: 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 help diagnose 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 20-25)
Cache results using the seed parameter for reproducibility

Pricing

Image generation costs are determined by fal.ai's pricing structure. Check fal.ai Pricing for current rates.

License

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

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues related to:

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

Changelog

v1.1.0 (Latest)

🚀 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: Full implementation of Hunyuan Image model via fal.ai
🔧 Fixed connection drops: Removed process.exit() calls that caused server crashes
🛡️ Improved error handling: Server continues running even without API key
🌍 Added portability: npx configuration works on any machine
📦 Enhanced stability: Graceful shutdown handlers and null safety checks
💬 Better user experience: Clear error messages with setup instructions
🔄 Auto-updating: npx pulls latest version from GitHub automatically
📁 Local image storage: Downloads generated images to local directory
🎯 Advanced parameters: Support for all Hunyuan Image parameters including prompt enhancement
⚡ Performance optimization: Configurable inference steps and guidance scale
🛡️ Safety features: Built-in content safety checking