# Higgsfield Unlimited MCP

An [MCP](https://modelcontextprotocol.io) server for **Higgsfield AI** that drives the
generation API in **unlimited mode** (`use_unlim: true`) — the same call the official web
app makes. It authenticates with your existing browser session (Clerk JWT, auto-refreshed),
runs **multiple accounts in parallel**, and covers image, video, audio, upload, cost
preview and job management.

> Unlimited is granted per model + account by Higgsfield's server. This client sends the
> unlimited flag exactly like the web app; the server decides. Check `unlimited_status`
> before generating — if a model isn't unlimited-active for you it costs credits
> (`estimate_cost`).

**Covered (34 tools):** image (v1 + v2 models), video (text-to-video & image-to-video,
9:16, resolution fallback), audio (TTS + voice list), local-file upload, multi-account
pool, cost/unlimited status, workspaces, media library, assets, job management.

---

## Requirements

- Python 3.10+
- Claude Code (CLI, or the VS Code / JetBrains extension) — or any MCP client
- An active Higgsfield login in your browser

## 1. Install

```bash
pip install git+https://github.com/nukIeer/higgsfield-unlimited-mcp.git
```

Or from a local clone (what you have now):

```bash
pip install -e .
```

## 2. Get your credentials (~2 min)

Open <https://higgsfield.ai> in your browser, logged in. Then in DevTools (`F12`):

1. **Session id** — Console tab, run:
   ```js
   window.Clerk.session.id        // → sess_xxxxxxxx
   ```
2. **`__client` cookie** — Application → Cookies → `https://higgsfield.ai` → copy the
   `__client` value (it's `httpOnly`, so it won't show in `document.cookie`).
3. **`datadome` cookie** — Console tab, run:
   ```js
   document.cookie    // copy the datadome=... part
   ```
   The `/jobs` endpoint sits behind DataDome bot protection; without this cookie
   generation returns a `403` captcha. **This cookie rotates** — refresh it if you start
   getting 403s.

Put them in a `.env` file in the project root (copy `.env.example`):

```ini
HIGGSFIELD_SESSION_ID=sess_xxxx
HIGGSFIELD_CLERK_COOKIE=eyJ...
HIGGSFIELD_EXTRA_COOKIES=datadome=xxxx
HIGGSFIELD_DEFAULT_MODEL=nano-banana-2
HIGGSFIELD_DEFAULT_RESOLUTION=2k
```

`.env` is gitignored — your credentials never leave your machine.

## 3. Connect it to Claude Code (VS Code)

The server reads credentials from your `.env` via `HIGGSFIELD_DOTENV` (an absolute path),
so no secrets go into the MCP config file.

**Project-scoped** — create `.mcp.json` in the project root:

```json
{
  "mcpServers": {
    "higgsfield-unlimited": {
      "command": "python",
      "args": ["-m", "higgsfield_unlimited_mcp"],
      "env": {
        "HIGGSFIELD_DOTENV": "C:\\Users\\TESST\\Desktop\\higgsfield-unlimited-mcp\\.env"
      }
    }
  }
}
```

**Or user-scoped** (works in every project) — add the same `mcpServers` block to
`~/.claude.json`.

**Or via the CLI:**

```bash
claude mcp add higgsfield-unlimited -s user -- python -m higgsfield_unlimited_mcp
```

Then reload the window / restart Claude Code. Verify the tools are live by asking:

> Use higgsfield-unlimited to run `auth_status`, then `unlimited_status`.

## 4. Verify (optional, CLI)

```bash
higgsfield-unlimited-verify --skip-generate    # auth + endpoints only, no credits
```

---

## Multiple accounts (parallel generation)

One account serialises behind a per-account rate limit (`429 rate_limit_reached`). Add more
accounts and the pool load-balances and fails a job over to another account on 429. Numbered
credentials, each with its own session id, `__client`, and `datadome`:

```ini
HIGGSFIELD_SESSION_ID_2=sess_bbbb
HIGGSFIELD_CLERK_COOKIE_2=eyJ...
HIGGSFIELD_EXTRA_COOKIES_2=datadome=bbbb
HIGGSFIELD_SESSION_ID_3=sess_cccc
HIGGSFIELD_CLERK_COOKIE_3=eyJ...
HIGGSFIELD_EXTRA_COOKIES_3=datadome=cccc
```

`auth_status` lists every account; `queue_status` shows per-account load; jobs and every
prompt in `generate_image_batch` route to the least-busy account. Pin a job to one account
with `account="account-2"` (needed when you pass a pre-uploaded media id — ids are
account-scoped).

---

## Tools

### Auth, account & cost
`auth_status` · `account_info` · `unlimited_status` (what's unlimited-active) ·
`estimate_cost` (credit table, no spend) · `concurrent_state` · `queue_status`

### Models
`list_models` (with `unlimited` + `api_version` per model) · `get_aspect_dimensions`

### Image
`generate_image` (v1 dash ids like `nano-banana-2`; v2 underscore ids like `seedream_v5_pro`,
`flux_2`, `gpt_image_2` with `api_version="v2"`) · `generate_image_batch` · `generate_storyboard`

### Video
`generate_video` — v2, defaults to viral **9:16**, image-to-video via `input_files`,
resolution fallback `1080p → 720p → 480p`. Unlimited video models: `seedance_2_0`,
`seedance_2_0_mini`, `wan2_7`, `gemini_omni`, `kling3_0`.

### Audio
`generate_audio` (TTS, `text2speech_v2`, multilingual incl. Turkish) · `list_voices`

### Upload & media
`media_upload` (local file → IP-checked media id) · `show_medias` · `media_status` ·
`media_download_batch`

### Jobs
`check_job` · `wait_for_job` · `cancel_job` · `list_jobs` · `download_job_result` ·
`show_generations`

### Workspaces & assets
`list_workspaces` · `workspace_details` · `workspace_wallet` · `workspace_members` ·
`workspace_usage` · `list_assets` · `list_favourites` · `like_asset` · `unlike_asset`

### Advanced
`generate_raw` (any model + `api_version`, custom params — face-swap, upscale, inpaint,
outpaint, explainer, …)

---

## Usage examples (ask Claude in plain language)

**Check what's free before spending:**
> Run `unlimited_status`, then `estimate_cost`.

**Image — first frame for a video:**
> Generate a 9:16 image with `nano-banana-2`: "messy salon appointment notebook, warm evening light, cinematic".

**Video — viral 9:16 (text-to-video):**
> Generate a 5s 9:16 video with `seedance_2_0`: "neon city rain at night, moody" (let it fall back to 720p).

**Image-to-video (animate a local frame):**
> Animate `./frame.jpg` into a 9:16 video with `kling3_0`, `input_files=["./frame.jpg"]`.

**Turkish voiceover:**
> `list_voices`, pick a female voice, then `generate_audio` that voice: "Randevularınızı tek yerden yönetin."

**Batch across accounts:**
> `generate_image_batch` these 8 prompts at 9:16, fire-and-forget — then `queue_status`.

---

## How it works

- **Auth** — the long-lived `__client` cookie mints short-lived Clerk JWTs
  (`POST clerk.higgsfield.ai/v1/client/sessions/{id}/tokens`), cached and refreshed
  proactively; a 401 forces a re-mint + one retry.
- **Unlimited** — every job sets `use_unlim: true` in `params` and the top-level body.
  The server enforces entitlement per model/account and returns
  `403 unlimited_generation_not_allowed` when not covered.
- **Two API generations** — v1 `POST /jobs/{dash-id}` (`input_images`), v2
  `POST /jobs/v2/{underscore_id}` (`medias:[{role,data}]`, `model` field). Video and newer
  models are v2.
- **DataDome** — the create endpoint is bot-protected; the client forwards your browser's
  `datadome` cookie so your session is recognised. It does not solve challenges.

See [`docs/EXTENDING.md`](docs/EXTENDING.md) and
[`docs/MODEL_SCHEMAS.md`](docs/MODEL_SCHEMAS.md) for the full verified request contracts
(upload flow, video params, TTS, IP-check, endpoints).

## Security

- Never commit `.env` — it's gitignored. Cookies equal your logged-in session; treat them
  like passwords.
- Credentials stay local — sent only to Higgsfield's own API.
- Rapid automated requests can trip DataDome (a browser verification / temporary IP flag).
  The client **throttles itself** — a minimum gap (+random jitter) between API calls per
  account (`HIGGSFIELD_MIN_REQUEST_INTERVAL`, default 1.5s; raise to 2.5–3s if you still
  see 403s). Refresh the `datadome` cookie if 403s persist.

## License

MIT — see [LICENSE](LICENSE).