# Higgsfield MCP

MCP server for [Higgsfield AI](https://higgsfield.ai) — generate images and videos with 16+ models through Claude, Cursor, or any MCP-compatible client.

## Models

### Image
| Model | ID | Key Features |
|---|---|---|
| Nano Banana 2 | `nano-banana-2` | Fast, reference images (up to 16), 1k/2k/4k |
| Nano Banana 1 | `nano-banana-1` | Reference images, multi-ref |
| Soul v2 | `soul-v2` | Stylized, 720p/1080p/2k |
| OpenAI Hazel | `openai-hazel` | GPT-Image-1.5, low/medium/high/4k |

### Video
| Model | ID | Key Features |
|---|---|---|
| Kling 3.0 | `kling3` | Best quality, start/end frames, sound, 720p/1080p, std/pro |
| Kling 3.0 Omni FLF | `kling-o3-flf` | First/last frame control |
| Kling 2.6 | `kling2-6` | Balanced quality/cost |
| Kling 2.5 Turbo | `kling2-5-turbo` | Unlimited plan credits |
| Kling 2.1 | `kling` | Budget option |
| Grok Video | `grok` | xAI video model |
| Wan 2.6 | `wan2-6` | Open-source model |
| Wan 2.5 | `wan2-5-video` | 16:9 or 9:16 only |
| Seedance 1.5 | `seedance1-5` | ByteDance latest |
| Seedance Pro | `seedance` | ByteDance pro |
| Veo 3 | `veo3` | Google DeepMind |
| Sora 2 | `sora2-video` | OpenAI, 4/8/12s durations |
| Image2Video | `image2video` | Requires input image |

## Tools

| Tool | Description |
|---|---|
| `higgsfield_generate_image` | Generate images (returns job_id) |
| `higgsfield_generate_video` | Generate videos (returns job_id) |
| `higgsfield_wait_for_job` | Poll job(s) until complete, return result URLs |
| `higgsfield_get_job` | Check single job status (no polling) |
| `higgsfield_list_jobs` | List recent jobs with status and URLs |
| `higgsfield_cancel_job` | Cancel a running job |
| `higgsfield_check_cost` | Dry-run cost estimate for image generation |
| `higgsfield_get_credits` | Account balance and plan info |
| `higgsfield_list_models` | List all models with supported parameters |
| `higgsfield_video_pricing` | Static pricing reference |
| `higgsfield_browser_status` | Check Helm daemon connection |
| `higgsfield_refresh_token` | Manually set JWT token |
| `higgsfield_refresh_credentials` | Update Clerk session cookies for auto-refresh |

## Prerequisites

- [Bun](https://bun.sh) runtime
- A [Higgsfield AI](https://higgsfield.ai) account (with credits)
- [Helm daemon](https://github.com/nicholasgasior/helm) running with Chrome extension — used to get auth tokens from your browser session
- *(Optional)* [curl-impersonate](https://github.com/lwthiker/curl-impersonate) — improves reliability for GET requests. Set `CURL_IMPERSONATE_BIN` env var if the binary isn't in PATH. Falls back to native `fetch` if not installed.

## Setup

```bash
# Clone
git clone https://github.com/jfikrat/higgsfield-mcp.git
cd higgsfield-mcp

# Install dependencies
bun install

# Run the server
bun run src/index.ts
```

### Claude Code / Claude Desktop

Add to your MCP config (`~/.claude/claude_desktop_config.json` or MCP settings):

```json
{
  "mcpServers": {
    "higgsfield": {
      "command": "bun",
      "args": ["run", "/path/to/higgsfield-mcp/src/index.ts"]
    }
  }
}
```

### Authentication

The server authenticates via Clerk session tokens from your Higgsfield browser session. There are three methods (tried in order):

1. **Auto-refresh** — Clerk API refresh using saved session cookies (preferred)
2. **Helm browser bridge** — Extracts token from your logged-in Chrome session via Helm daemon
3. **Manual** — Paste a JWT token via `higgsfield_refresh_token`

**First-time setup:**

1. Log in to [higgsfield.ai](https://higgsfield.ai) in Chrome
2. Make sure the Helm daemon is running (`systemctl --user start helm-daemon`)
3. Use `higgsfield_browser_status` to verify the connection
4. The server will auto-extract tokens from your browser session

**If auto-refresh stops working** (tokens expire ~every 7 days):

1. Open Chrome DevTools on higgsfield.ai
2. Copy cookies from the `clerk.higgsfield.ai` domain
3. Run `higgsfield_refresh_credentials` with the cookie string

Settings are stored at `~/.config/higgsfield-mcp/settings.json` (permissions: 600).

## Architecture

```
src/
├── index.ts          # MCP server entry point
├── models.ts         # Model metadata, validation, param builders
├── api.ts            # HTTP client (GET/POST/DELETE)
├── auth.ts           # Token management (Clerk refresh + browser fallback)
├── browser-post.ts   # Helm daemon bridge for browser-based POST
├── curl-fetch.ts     # curl-impersonate wrapper with native fallback
├── config.ts         # Secure settings storage (~/.config/higgsfield-mcp/)
├── tracker.ts        # Generation gallery tracker
└── tools/
    ├── account.ts    # Account, credits, model listing tools
    ├── image.ts      # Image generation tools
    └── video.ts      # Video generation + job polling tools
```

## How It Works

Higgsfield uses [DataDome](https://datadome.co/) bot protection that blocks non-browser POST requests. This server handles it with a two-layer approach:

- **GET/DELETE** requests go through `curl-impersonate` (or native `fetch` as fallback) with browser-like TLS fingerprints
- **POST** requests are routed through the Helm daemon, which executes `fetch()` inside your actual Chrome tab on higgsfield.ai — DataDome sees a real browser

## License

MIT