Higgsfield AI MCP Server

MCP (Model Context Protocol) server for Higgsfield AI API - enabling AI-powered image generation, video creation, and speech synthesis capabilities.

Features

🎨 Text-to-Image (Soul Model)

• Generate high-quality images from text prompts
• Multiple image sizes and quality options
• Custom style presets and character references
• Batch generation support

🎬 Image-to-Video (DOP Model)

• Animate static images with motion presets
• Start and end frame support
• Customizable motion strength

🗣️ Speech-to-Video

• Generate talking head videos
• Custom image and audio input
• Adjustable quality and duration

👤 Character Management

• Create consistent character references
• Use across multiple generations
• Manage character library

📊 Job Management

• Async job status tracking
• Webhook notifications
• Result retrieval

Installation

Prerequisites

• Python 3.10 or higher
• Higgsfield AI API credentials (Get them here)

Install via pip

pip install higgsfield-mcp

Install from source

git clone <repository-url>
cd higgsfield-mcp
pip install -e .

🚀 Quick Setup for Claude Code

Using Claude Code CLI? See CLAUDE_CODE_SETUP.md for step-by-step instructions.

TL;DR:

1. pip install higgsfield-mcp
2. Add to .mcp.json:

{
  "mcpServers": {
    "higgsfield": {
      "command": "higgsfield-mcp",
      "env": {
        "HIGGSFIELD_API_KEY": "your-key",
        "HIGGSFIELD_SECRET": "your-secret"
      }
    }
  }
}

3. Restart Claude Code and start generating!

Configuration

1. Set up environment variables

Create a .env file in your project directory:

HIGGSFIELD_API_KEY=your-api-key-here
HIGGSFIELD_SECRET=your-secret-here

Or export them in your shell:

export HIGGSFIELD_API_KEY=your-api-key-here
export HIGGSFIELD_SECRET=your-secret-here

2. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop config.json):

{
  "mcpServers": {
    "higgsfield": {
      "command": "python",
      "args": ["-m", "higgsfield_mcp.server"],
      "env": {
        "HIGGSFIELD_API_KEY": "your-api-key-here",
        "HIGGSFIELD_SECRET": "your-secret-here"
      }
    }
  }
}

Or if installed via pip:

{
  "mcpServers": {
    "higgsfield": {
      "command": "higgsfield-mcp",
      "env": {
        "HIGGSFIELD_API_KEY": "your-api-key-here",
        "HIGGSFIELD_SECRET": "your-secret-here"
      }
    }
  }
}

Available Tools

Text-to-Image

generate_image_soul

Generate images from text prompts using the Soul model.

Parameters:

• prompt (required): Text description of the image
• width_and_height (optional): Image dimensions (default: "1696x960")
  • Options: "1152x2048", "2048x1152", "2048x1536", "1536x2048", etc.
• enhance_prompt (optional): Auto-enhance prompt (default: true)
• quality (optional): "720p" or "1080p" (default: "720p")
• batch_size (optional): 1 or 4 (default: 1)
• style_id (optional): Style preset UUID
• style_strength (optional): 0-1 (default: 1.0)
• seed (optional): 1-1000000 for reproducibility
• custom_reference_id (optional): Character reference UUID
• custom_reference_strength (optional): 0-1 (default: 1.0)
• image_reference_url (optional): Reference image URL
• webhook_url (optional): Webhook for completion notification
• webhook_secret (optional): Webhook secret

Example:

{
  "prompt": "A serene mountain landscape at sunset",
  "width_and_height": "2048x1152",
  "quality": "1080p",
  "enhance_prompt": true
}

get_soul_styles

Get list of available style presets.

Returns: List of styles with id, name, description, and preview_url

---

Image-to-Video

generate_video_dop

Generate video from static image using DOP model.

Parameters:

• input_image_url (required): Source image URL
• prompt (required): Animation description
• model (optional): Model name (default: "dop-turbo")
• seed (optional): Reproducibility seed
• motions (optional): Array of motion presets [{id, strength}]
• input_image_end_url (optional): End frame URL
• enhance_prompt (optional): Auto-enhance (default: true)
• webhook_url (optional): Completion webhook
• webhook_secret (optional): Webhook secret

Example:

{
  "input_image_url": "https://example.com/image.jpg",
  "prompt": "The person slowly turns their head and smiles",
  "motions": [
    {"id": "motion-uuid", "strength": 0.7}
  ]
}

get_motions

Get list of available motion presets.

Returns: List of motions with id, name, description, and preview_url

---

Speech-to-Video

generate_speech_video

Generate talking head video from text.

Parameters:

• prompt (required): Speech text
• input_image_url (optional): Face image URL
• input_audio_url (optional): Audio URL
• quality (optional): Quality setting (default: "high")
• enhance_prompt (optional): Auto-enhance (default: false)
• seed (optional): Reproducibility seed
• duration (optional): Duration in seconds
• webhook_url (optional): Completion webhook
• webhook_secret (optional): Webhook secret

Example:

{
  "prompt": "Hello, welcome to our presentation!",
  "input_image_url": "https://example.com/face.jpg",
  "quality": "high"
}

---

Character Management

create_character

Create a custom character reference for consistent generation.

Parameters:

• name (required): Character name (max 100 chars)
• image_urls (required): Array of 1-100 image URLs

Example:

{
  "name": "My Character",
  "image_urls": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg"
  ]
}

Returns: Character object with id to use in custom_reference_id

get_character

Get character details and processing status.

Parameters:

• reference_id (required): Character UUID

delete_character

Delete a character reference.

Parameters:

• reference_id (required): Character UUID

---

Job Management

get_job_status

Check status and retrieve results of a generation job.

Parameters:

• job_set_id (required): Job set UUID (returned from generation calls)

Returns: Job details with status and result URLs

---

Usage Examples

Example 1: Generate an Image

# Using MCP client
result = await client.call_tool(
    "generate_image_soul",
    {
        "prompt": "A cyberpunk city at night with neon lights",
        "width_and_height": "2048x1152",
        "quality": "1080p"
    }
)

# Get the job_set_id from result
job_set_id = result["id"]

# Check status
status = await client.call_tool(
    "get_job_status",
    {"job_set_id": job_set_id}
)

Example 2: Create Character and Use in Generation

# Create character
character = await client.call_tool(
    "create_character",
    {
        "name": "John Doe",
        "image_urls": ["https://example.com/john.jpg"]
    }
)

character_id = character["id"]

# Wait for character to be ready
while True:
    status = await client.call_tool(
        "get_character",
        {"reference_id": character_id}
    )
    if status["status"] == "completed":
        break
    await asyncio.sleep(5)

# Generate image with character
result = await client.call_tool(
    "generate_image_soul",
    {
        "prompt": "Professional headshot in a suit",
        "custom_reference_id": character_id,
        "custom_reference_strength": 0.8
    }
)

Example 3: Animate an Image

# Get available motions
motions = await client.call_tool("get_motions", {})

# Generate video
result = await client.call_tool(
    "generate_video_dop",
    {
        "input_image_url": "https://example.com/portrait.jpg",
        "prompt": "Person looks around with a gentle smile",
        "motions": [
            {"id": motions[0]["id"], "strength": 0.6}
        ]
    }
)

API Response Format

Generation requests return a job set object:

{
  "id": "job-set-uuid",
  "type": "text2image_soul",
  "created_at": "2023-11-07T05:31:56Z",
  "jobs": [
    {
      "id": "job-uuid",
      "job_set_type": "text2image_soul",
      "status": "queued",
      "results": {
        "min": {
          "type": "image_url",
          "url": "https://..."
        },
        "raw": {
          "type": "image_url",
          "url": "https://..."
        }
      }
    }
  ],
  "input_params": {}
}

Job Statuses:

• queued - Job is waiting to start
• in_progress - Job is processing
• completed - Job finished successfully
• failed - Job failed
• nsfw - Content filtered

Webhooks

For async workflows, provide a webhook URL to receive notifications when jobs complete:

{
  "prompt": "...",
  "webhook_url": "https://your-server.com/webhook",
  "webhook_secret": "your-secret"
}

Webhook payload matches the job set format with completed results.

Error Handling

The server returns descriptive error messages:

{
  "error": "Higgsfield API Error: API request failed with status 422: ..."
}

Common errors:

• 401: Invalid API credentials
• 422: Invalid parameters
• 500: Generation failed

Development

Setup Development Environment

# Clone repository
git clone <repository-url>
cd higgsfield-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check .

Project Structure

higgsfield-mcp/
├── src/
│   └── higgsfield_mcp/
│       ├── __init__.py
│       ├── client.py       # Higgsfield API client
│       └── server.py       # MCP server implementation
├── tests/
│   └── test_client.py
├── pyproject.toml
├── README.md
└── .env.example

Resources

• Higgsfield AI Documentation
• MCP Protocol Specification
• Get API Credentials

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Higgsfield API: docs.higgsfield.ai
• MCP Server: Open an issue on GitHub

---

Made with ❤️ for the MCP ecosystem