Skip to main content
Glama
Higgsfield Unlimited MCP

Higgsfield Unlimited MCP

by nukIeer

Higgsfield Unlimited MCP

An MCP 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

Related MCP server: Higgsfield AI MCP Server

1. Install

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

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

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:

    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:

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

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:

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

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)

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:

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 and 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.

Available Tools

29 tools
account_infoB

Plan info, all credit balances, and the has_unlim flag.

Inputs: no named parameters. Returns: result

auth_statusA

Verify credentials for every configured account by minting a fresh JWT each.

Inputs: no named parameters. Returns: result

cancel_jobB

Cancel an in-progress job (DELETE /jobs/{id}).

Inputs: job_id (required). Returns: result

check_jobA

Poll a single job across the account pool (local registry, then remote API).

Inputs: job_id (required). Returns: result

concurrent_stateB

Concurrent-slot tier (how many jobs can run at once: 4/8/12/16).

Inputs: no named parameters. Returns: result

download_job_resultC

Re-fetch a completed job's results and save them to disk.

Inputs: job_id (required), output_dir. Returns: result

estimate_costA

Credit cost table per model / resolution / mode — WITHOUT spending credits.

Reads GET /job-sets/costs. Use this before generating on credits (unlimited jobs cost 0). e.g. seedance_2_0 720p ~4.5 credits/second; an 8s clip ~36 credits. Check unlimited_status first — if a model is unlimited-active for you, it's free.

Inputs: account. Returns: result

generate_audioB

Text-to-speech (unlimited) via the v2 text2speech_v2 model.

Verified contract: params {prompt, model:"elevenlabs", voice_id, voice_type:"preset"}. Get a voice_id from list_voices. Works with Turkish (and other languages) text.

Inputs: text (required), wait, model, account, +6 more. Returns: result

generate_imageC

Generate a single image, unlimited, across the account pool.

model uses the API path form: v1 models use dashes (nano-banana-2, nano-banana-pro); v2 models use underscores + api_version="v2" (seedream_v5_pro, seedream_v5_lite, flux_2, gpt_image_2, soul_2, kling_omni_image). Unlimited-eligible on a typical plan: nano_banana_2, nano_banana_pro, gpt_image_2, seedream_v5_pro, seedream_v4_5, soul_2, seedream_v5_lite, flux_2, kling_omni_image. Local input_files are auto-uploaded. See list_models and account_info for what's unlimited on your plan.

Inputs: prompt (required), seed, wait, model, +11 more. Returns: result

generate_image_batchA

Queue many prompts, running up to max_concurrent in parallel.

With wait=False (default) this fires all jobs and returns their ids — poll progress with queue_status / list_jobs. With wait=True it blocks until every job finishes.

Inputs: prompts (required), wait, model, timeout, +7 more. Returns: result

generate_rawA

Escape hatch: call any model with a custom params dict, across the account pool.

Use for face-swap, character-swap, upscale, inpaint, or any model whose exact schema you already know (see docs/MODEL_SCHEMAS.md). params is passed through verbatim (with use_unlim added). api_version selects the endpoint: v1 (/jobs/{model}) or v2 (/jobs/v2/{model}, newer models incl. most video). Local input_files are uploaded and merged into params['input_images'].

Inputs: model (required), params (required), kind, wait, +4 more. Returns: result

generate_storyboardB

Multi-shot storyboard with character/style continuity.

Uses Higgsfield's dedicated multi-shot endpoint (nano-banana-2-shots). Each entry in shots is one shot's prompt; an optional reference image is shared across every shot for continuity.

Inputs: shots (required), wait, model, timeout, +6 more. Returns: result

generate_videoA

Generate ONE video via the v2 API, with automatic resolution fallback.

Defaults target viral 9:16 clips. Unlimited is capped per model (Seedance/Wan/Gemini render unlimited at 720p), so resolution_fallback walks 1080p -> 720p -> 480p when the server denies unlimited. To make MANY videos in parallel across your accounts, use generate_video_batch (one generate_video call = one account = sequential).

Unlimited-eligible: seedance_2_0, seedance_2_0_mini, wan2_7, gemini_omni, kling3_0. Local input_files are uploaded as the start_image (image-to-video).

Inputs: prompt (required), mode, seed, wait, +13 more. Returns: result

generate_video_batchA

Generate MANY videos in PARALLEL, spread across all accounts in the pool.

This is how you use multiple accounts at once: N prompts fan out concurrently and the pool routes each to the least-busy account (with 429 failover). With wait=True (default) it returns when all are done; wait=False fires them and returns job ids to poll with queue_status. For image-to-video per prompt, pass input_files_per_prompt=[["a.jpg"], ["b.jpg"], ...] aligned to prompts.

Inputs: prompts (required), mode, wait, model, +10 more. Returns: result

get_aspect_dimensionsB

Canonical (width, height) in pixels for an aspect ratio + resolution (1k/2k/4k).

Inputs: aspect_ratio (required), resolution. Returns: result

list_jobsA

List all jobs across every account in the pool (this session).

Inputs: no named parameters. Returns: result

list_modelsA

List generation models. Optionally filter by category: image / video / audio.

Inputs: category. Returns: result

list_voicesA

List TTS preset voices (id, name, gender, preview mp3) for generate_audio.

Reads GET /reference-elements/voices. Pick a voice id and pass it to generate_audio as voice_id. Turkish voiceover: choose a voice and write the prompt in Turkish — ElevenLabs is multilingual.

Inputs: size, account. Returns: result

list_workspacesA

List all your workspaces.

Inputs: no named parameters. Returns: result

media_statusB

Check status of media items by id.

Inputs: media_ids (required). Returns: result

media_uploadB

Upload a local image/video for use as input on subsequent generations.

Inputs: file_path (required). Returns: result

queue_statusA

Snapshot of in-flight jobs across all accounts in the pool.

Inputs: no named parameters. Returns: result

show_generationsC

Server-side recent generation history (your account's /jobs/accessible).

Inputs: limit, offset. Returns: result

show_mediasA

Paginated media library (images + videos). Optional kind filter: image/video.

Inputs: kind, limit, offset. Returns: result

unlimited_statusA

Which models are currently unlimited-active for the account.

Reads /workspaces/unlim-activations, /subscriptions/bundle/all-unlim/status, and /user (has_unlim). An empty activations list means no active unlimited right now — generation would then cost credits (see estimate_cost).

Inputs: account. Returns: result

wait_for_jobA

Block until a job finishes; optionally download its results.

Inputs: job_id (required), timeout, download, interval. Returns: result

workspace_detailsA

Active workspace info (id, name, type, role).

Inputs: no named parameters. Returns: result

workspace_usageB

Credit-usage chart for the active workspace.

Inputs: no named parameters. Returns: result

workspace_walletC

Workspace credit balance.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target a distinct endpoint or lifecycle stage, and the detailed descriptions make choices like estimate_cost vs unlimited_status vs account_info reasonably clear. A few query tools still overlap in purpose (account_info vs workspace_wallet, list_jobs vs queue_status vs show_generations), so an agent could occasionally misselect.

    Naming Consistency4/5

    Action tools mostly follow a clear verb_noun pattern (list_*, generate_*, check_*, cancel_*, download_*), while status tools are grouped as *_status/*_info nouns. Minor inconsistencies like media_upload instead of upload_media, show_medias vs media_status, and the mix of noun-led and verb-led names keep it from being fully consistent.

    Tool Count3/5

    29 tools is on the heavy side for an MCP server, though the scope is broad: image/video/audio generation, account/workspace management, credits, jobs, and media. Several status/query tools could be consolidated, making the set feel larger than necessary, but each tool does map to a distinct backend capability.

    Completeness4/5

    The generation lifecycle is well covered: single/batch image and video generation, storyboard, audio TTS, raw escape hatch, media upload/status/library, job polling/cancellation/download, and workspace/credit status. Minor gaps like no media delete/detail endpoint and no audio batch variant are workable but keep it from being fully complete.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers