fal-ai/hidream-i1-full MCP Server

A Model Context Protocol (MCP) server that provides access to the fal-ai/hidream-i1-full image generation model. This server allows you to generate high-quality images using advanced AI technology through the fal.ai platform.

Features

• High-Quality Image Generation: Generate stunning images using the fal-ai/hidream-i1-full model

• Multiple Generation Methods: Support for synchronous, streaming, and queue-based generation

• Flexible Image Sizing: Support for predefined sizes and custom dimensions

• Advanced Parameters: Control over inference steps, guidance scale, safety checker, and more

• LoRA Support: Apply custom LoRA weights for specialized image styles

• Local Image Download: Automatically downloads generated images to local storage

• Queue Management: Submit long-running requests and check their status

• Webhook Support: Optional webhook notifications for completed requests

Installation

1. Clone this repository:

git clone https://github.com/PierrunoYT/fal-hidream-i1-full-mcp-server.git
cd fal-hidream-i1-full-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Set your fal.ai API key as an environment variable:

export FAL_KEY="your_fal_api_key_here"

You can get your API key from fal.ai.

MCP Client Configuration

Add this server to your MCP client configuration. For example, in Claude Desktop's config file:

{
  "mcpServers": {
    "fal-hidream-i1-full": {
      "command": "node",
      "args": ["/path/to/fal-hidream-i1-full-mcp-server/build/index.js"],
      "env": {
        "FAL_KEY": "your_fal_api_key_here"
      }
    }
  }
}

Available Tools

1. hidream_i1_full_generate

Generate images using the standard synchronous method.

Parameters:

• prompt (required): Text description of the image to generate

• negative_prompt (optional): What you don't want in the image

• image_size (optional): Predefined size or custom {width, height} object

• num_inference_steps (optional): Number of inference steps (1-100, default: 50)

• seed (optional): Random seed for reproducible results

• guidance_scale (optional): CFG scale (1-20, default: 5)

• sync_mode (optional): Wait for completion (default: true)

• num_images (optional): Number of images to generate (1-4, default: 1)

• enable_safety_checker (optional): Enable safety filtering (default: true)

• output_format (optional): "jpeg" or "png" (default: "jpeg")

• loras (optional): Array of LoRA weights to apply

Example:

{
  "prompt": "a cat holding a skateboard which has 'fal' written on it in red spray paint",
  "image_size": {"width": 1024, "height": 1024},
  "num_inference_steps": 50,
  "guidance_scale": 7.5
}

2. hidream_i1_full_generate_stream

Generate images using streaming for real-time progress updates.

Parameters: Same as hidream_i1_full_generate

3. hidream_i1_full_generate_queue

Submit a long-running image generation request to the queue.

Parameters: Same as hidream_i1_full_generate plus:

• webhook_url (optional): URL for webhook notifications

Returns: A request ID for tracking the job

4. hidream_i1_full_queue_status

Check the status of a queued request.

Parameters:

• request_id (required): The request ID from queue submission

• logs (optional): Include logs in response (default: true)

5. hidream_i1_full_queue_result

Get the result of a completed queued request.

Parameters:

• request_id (required): The request ID from queue submission

Image Sizes

Predefined Sizes

• square_hd: High-definition square

• square: Standard square

• portrait_4_3: Portrait 4:3 aspect ratio

• portrait_16_9: Portrait 16:9 aspect ratio

• landscape_4_3: Landscape 4:3 aspect ratio

• landscape_16_9: Landscape 16:9 aspect ratio

Custom Sizes

You can also specify custom dimensions:

{
  "image_size": {
    "width": 1280,
    "height": 720
  }
}

LoRA Support

Apply custom LoRA weights for specialized styles:

{
  "loras": [
    {
      "path": "https://example.com/lora-weights.safetensors",
      "scale": 1.0,
      "weight_name": "optional_weight_name"
    }
  ]
}

Output

Generated images are automatically downloaded to a local images/ directory with descriptive filenames. The response includes:

• Local file paths

• Original URLs

• Image dimensions

• Content types

• Generation parameters used

• Request IDs for tracking

Error Handling

The server provides detailed error messages for:

• Missing API keys

• Invalid parameters

• Network issues

• API rate limits

• Generation failures

Development

Running in Development Mode

npm run dev

Testing the Server

npm test

Getting the Installation Path

npm run get-path

API Reference

This server implements the fal-ai/hidream-i1-full API. For detailed API documentation, visit:

• fal.ai Documentation

• fal.ai Client Library

License

MIT License - see 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 and questions:

• Open an issue on GitHub

• Check the fal.ai documentation

Changelog

v2.0.0

• Complete rewrite to use fal-ai/hidream-i1-full API

• Added streaming support

• Added queue management

• Added LoRA support

• Improved error handling

• Updated to latest MCP SDK