# Higgsfield AI MCP Server

MCP (Model Context Protocol) server for [Higgsfield AI](https://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](https://platform.higgsfield.ai))

### Install via pip

```bash
pip install higgsfield-mcp
```

### Install from source

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

### 🚀 Quick Setup for Claude Code

Using Claude Code CLI? See **[CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md)** for step-by-step instructions.

**TL;DR:**
1. `pip install higgsfield-mcp`
2. Add to `.mcp.json`:
```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:

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

Or export them in your shell:

```bash
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`):

```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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```python
# 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

```python
# 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

```python
# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
# 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](https://docs.higgsfield.ai/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Get API Credentials](https://platform.higgsfield.ai/)

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Higgsfield API: [docs.higgsfield.ai](https://docs.higgsfield.ai/)
- MCP Server: Open an issue on GitHub

---

**Made with ❤️ for the MCP ecosystem**