Higgsfield Unlimited MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Higgsfield Unlimited MCP generate an unlimited image of a serene lake at sunset"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_statusbefore 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.gitOr 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):
Session id — Console tab, run:
window.Clerk.session.id // → sess_xxxxxxxx__clientcookie — Application → Cookies →https://higgsfield.ai→ copy the__clientvalue (it'shttpOnly, so it won't show indocument.cookie).datadomecookie — Console tab, run:document.cookie // copy the datadome=... partThe
/jobsendpoint sits behind DataDome bot protection; without this cookie generation returns a403captcha. 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_mcpThen reload the window / restart Claude Code. Verify the tools are live by asking:
Use higgsfield-unlimited to run
auth_status, thenunlimited_status.
4. Verify (optional, CLI)
higgsfield-unlimited-verify --skip-generate # auth + endpoints only, no creditsMultiple 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=ccccauth_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, thenestimate_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.jpginto a 9:16 video withkling3_0,input_files=["./frame.jpg"].
Turkish voiceover:
list_voices, pick a female voice, thengenerate_audiothat voice: "Randevularınızı tek yerden yönetin."
Batch across accounts:
generate_image_batchthese 8 prompts at 9:16, fire-and-forget — thenqueue_status.
How it works
Auth — the long-lived
__clientcookie 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: trueinparamsand the top-level body. The server enforces entitlement per model/account and returns403 unlimited_generation_not_allowedwhen not covered.Two API generations — v1
POST /jobs/{dash-id}(input_images), v2POST /jobs/v2/{underscore_id}(medias:[{role,data}],modelfield). Video and newer models are v2.DataDome — the create endpoint is bot-protected; the client forwards your browser's
datadomecookie 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 thedatadomecookie if 403s persist.
License
MIT — see LICENSE.
Available Tools
29 toolsaccount_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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Hailuo (MiniMax) AI video generation
MCP server for Wan AI video generation
MCP server for Flux AI image generation
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for AI-powered media generation: images, videos, audio, and upscaling using 99 AI models.6MIT
- AlicenseNot gradedqualityDmaintenanceMCP server integrating Higgsfield AI API for image generation, video animation, and speech-to-video synthesis with character management and job tracking.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Higgsfield AI that enables image and video generation using 16+ models through Claude, Cursor, or any MCP-compatible client.3MIT
- FlicenseAqualityDmaintenanceStandalone MCP server and CLI for generating images via ChatGPT backend, with reliable exact file paths and multi-account login support.25-