higgsfield-mcp-unified
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-mcp-unified can you generate a photorealistic image of a cat in a spacesuit?"
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-mcp-unified
Unified Model Context Protocol (MCP) server for Higgsfield AI. It puts 43 Higgsfield image and video models — Sora 2, Veo 3.x, Kling 3.0, Seedance 2.0, Wan, Soul, DOP, Nano Banana, FLUX, and more — plus Soul character training, account/history, and talking-head speech behind a single, typed tool surface for any MCP client (Claude Desktop, Claude Code, Cursor, …).
Status: alpha. Local/self-hosted and not yet on PyPI — install from source (below). The cloud web backend is opt-in and experimental.
Why this over the hosted MCP
The official hosted MCP (mcp.higgsfield.ai) is great but runs on Higgsfield's servers behind OAuth. This one is local-first and adds things a hosted server can't:
Runs on your machine — prompts and media go straight to Higgsfield, no intermediary proxy.
Dual backend under one surface — routes per model across the official REST API and the cloud web app.
Typed structured output — every tool returns a schema'd result (
outputSchema+structuredContent), not an opaque blob.Discovery without burning a generation —
recommend_model,validate_params,preflight_check, and an MCP resource catalog.Reliability built in — retries with backoff + jitter (honoring
Retry-After), a circuit breaker, idempotency keys, and a structured error taxonomy.MCP prompt templates — reusable cinematic/product scaffolds.
Related MCP server: emaki
Backends
Official REST API (
platform.higgsfield.ai) — stable,KEY:SECRETauth. Default; rock-solid.Cloud web app (
fnf.higgsfield.ai) — the newest models, reachable only via a Clerk cookie. Opt-in and experimental (see warning below).
Install (from source)
Not published to PyPI yet. Clone and run with uv:
git clone https://github.com/Hikhakk/higgsfield-mcp-unified
cd higgsfield-mcp-unified
uv sync
uv run higgsfield-mcp # starts the stdio MCP serverConfigure
The official backend needs two environment variables:
export HIGGSFIELD_API_KEY=... # from the platform.higgsfield.ai dashboard
export HIGGSFIELD_SECRET=...To unlock the cloud-only models (Sora 2 / Veo 3.x / Kling 3.0 / …), opt in to the web backend:
export HIGGSFIELD_ENABLE_WEB_BACKEND=1
export HIGGSFIELD_CLERK_CLIENT=... # __client cookie from cloud.higgsfield.ai (lasts ~7 days)
# or, for one-shot tests only:
export HIGGSFIELD_JWT=... # __session cookie (expires in ~1 minute)Run preflight_check from your client to confirm both backends are reachable before generating.
Web backend is experimental and will likely break
The
cloud.higgsfield.ai/fnf.higgsfield.aisurface is not a public API — it is the consumer web app's private backend, integrated by reverse-engineering. Expect:
Auth churn. The Clerk JWT lives ~1 minute. The server refreshes it from a long-lived
__clientcookie, but Clerk rotates that cookie too (~7 days). When it rotates, paste a new one.Bot protection.
fnf.higgsfield.aisits behind Cloudflare's managed challenge (TLS fingerprinting). Browser-impersonating TLS (curl_cffi) clears it today, but it is brittle.Schema drift. Endpoint paths, body keys, and slugs are undocumented and change without notice. Several of the newest model endpoints in this server are marked
inferred(best-guess, hidden by default) until verified against live traffic.Probably against ToS. Driving the consumer app programmatically is almost certainly unsupported. Review the terms before enabling it.
Off by default. Without
HIGGSFIELD_ENABLE_WEB_BACKEND=1, only the official-API models are reachable, and that path is solid.
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"higgsfield": {
"command": "uv",
"args": ["run", "--directory", "/path/to/higgsfield-mcp-unified", "higgsfield-mcp"],
"env": {
"HIGGSFIELD_API_KEY": "...",
"HIGGSFIELD_SECRET": "..."
}
}
}
}Cursor / Claude Code / any stdio MCP client: point at the same uv run … higgsfield-mcp command and pass env vars. See examples/.
Tools
Tool | What it does |
| The model registry. Inferred (unverified) models are hidden unless |
| Rank models for a described goal (local, no API call). |
| Check params against a model's supported set before submitting. |
| Validate auth + reachability for both backends without spending a generation. |
| Submit a text-to-image / image-edit job (supports Soul character refs). |
| Submit a text-to-video / image-to-video job. |
| Fan out multiple image/video submits concurrently. |
| Talking-head video from a face image + WAV audio. |
| Poll, or long-poll until terminal, with output URLs. |
| Cancel a queued/in-progress job. |
| Upload a local image and get a hosted URL. |
| Train and manage reusable Soul characters. |
| Soul style and DOP motion presets, by name. |
| Available credits + plan (official backend). |
| Recent generations (history). |
Resources & prompts
Resources:
higgsfield://models(full catalog) andhiggsfield://models/{kind}— subscribe to the catalog instead of repeatedly callinglist_models.Prompts:
cinematic_shot,product_360,animate_portrait,action_sequence,b_roll— parameterized scaffolds to feed into the generation tools.
Models
Run list_models() (or read the higgsfield://models resource) for the live catalog. The registry carries a confidence tier:
verified— endpoint confirmed against SDK source / live probe (shown by default).inferred— slug confirmed real but the endpoint is a best-guess pending live verification (hidden unlessinclude_unverified=true, and noted as such).
Official backend (verified): Soul, Reve, Seedream v4 (text-to-image + edit), FLUX.1 Kontext Max, DOP (preview/standard), Seedance v1 Pro, Kling v2.1 Pro.
Cloud backend: Kling 3.0 / O3 FLF, Seedance 2.0 / 1.5, Wan 2.6, Veo 3, Grok, Sora 2, Nano Banana, Soul v2, OpenAI Hazel, and newest-tier inferred entries (Veo 3.1, Wan 2.7, Kling 3.0 Turbo, Hailuo 02, FLUX.2, Z-Image, Cinematic Studio, …).
Development
uv sync --extra dev
uv run --extra dev pytest -q
uv run --extra dev ruff check . && uv run --extra dev ruff format --check .
uv run --extra dev mypy srcDesign specs and phased implementation plans live in docs/superpowers/.
Contributing
PRs welcome. See CONTRIBUTING.md. Merges to main require code-owner approval (@Hikhakk) and green CI.
Credits
Built on two earlier community efforts:
geopopos/geo_higgsfield_ai_mcp— first Python MCP for the official API.jfikrat/higgsfield-mcp— first MCP to expose the cloud web models; source of the original model registry.
License
MIT — see LICENSE.
Available Tools
20 toolscancel_job_toolC
Cancel a queued or in-progress job.
Inputs: job_handle (required). Returns: cancelled, job_handle
create_character_toolC
Train a reusable Soul character from reference images. Results best-effort until verified.
Inputs: name (required), image_urls (required). Returns: id, raw, name, status, +1 more
delete_character_toolC
Delete a trained Soul character.
Inputs: character_id (required). Returns: deleted, character_id
generate_batch_toolB
Submit multiple generations at once. Each request: {kind, model_id, prompt, ...params}.
Inputs: requests (required). Returns: count, results
generate_image_toolC
Submit an image-generation request. Returns a job_handle to poll.
Inputs: prompt (required), model_id (required), seed, quality, +8 more. Returns: backend, model_id, job_handle
generate_speech_video_toolC
Talking-head video from a face image + WAV audio (official backend).
Inputs: audio_url (required), image_url (required), prompt. Returns: backend, model_id, job_handle
generate_video_toolC
Submit a video-generation request. Returns a job_handle to poll.
Inputs: prompt (required), model_id (required), seed, sound, +4 more. Returns: backend, model_id, job_handle
get_balance_toolA
Get available credits + plan (best-effort; official API key required).
Inputs: no named parameters. Returns: raw, plan, credits
get_character_toolC
Check a Soul character's training status.
Inputs: character_id (required). Returns: id, raw, name, status, +1 more
get_status_toolC
Check job state and return output URLs when ready.
Inputs: job_handle (required). Returns: error, state, images, timeout, +3 more
list_characters_toolC
List trained Soul characters.
Inputs: page, page_size. Returns: count, characters
list_jobs_toolC
List recent generations (history) from the official backend.
Inputs: page, page_size. Returns: jobs, count
list_models_toolC
List every supported Higgsfield model.
Inputs: kind, backend, include_unverified. Returns: count, models
list_motions_toolA
List DOP motion presets for image-to-video.
Inputs: no named parameters. Returns: raw, count, names
list_soul_styles_toolA
List Soul image style presets to pick by name.
Inputs: no named parameters. Returns: raw, count, names
preflight_check_toolA
Check auth + config for both backends before submitting a generation.
Inputs: no named parameters. Returns: web, official
recommend_model_toolB
Suggest models for a described goal. Ranks by keyword overlap; verified-only by default.
Inputs: intent (required), top, kind, include_unverified. Returns: intent, recommendations
subscribe_toolB
Long-poll until the job reaches a terminal state (completed/failed/etc).
Inputs: job_handle (required), poll_interval, timeout_seconds. Returns: error, state, images, timeout, +3 more
upload_image_toolC
Upload a local image and get a hosted URL to use as image_url.
Inputs: mime, path, backend, data_base64. Returns: url, backend
validate_params_toolB
Pre-flight check params against a model's supported set (no generation).
Inputs: params (required), model_id (required). Returns: valid, model_id, supported, constraints, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target distinct resource+action pairs (image vs video vs speech-video generation, character CRUD, model/job listing). The only mild overlap is get_status_tool vs subscribe_tool (both inspect job state) and the three pre-flight helpers (preflight_check, validate_params, get_balance), but descriptions make their separate targets clear.
Every tool follows the same verb_noun_tool convention (generate_image_tool, list_characters_tool, get_status_tool, cancel_job_tool), giving a fully predictable, uniform naming pattern with no deviations.
20 tools is on the heavier side but each covers a plausibly needed capability across generation, character lifecycle, presets, job control, and utilities. It leans verbose (several discovery/validation helpers) but nothing is clearly redundant.
Strong coverage: generation (image/video/speech/batch), full character CRUD, job status/cancel/subscribe, upload, model/style/motion discovery, balance, and pre-flight validation. Minor gaps like job history deletion or character update are absent but not blocking for the core workflow.
Maintenance
Related MCP Connectors
Generate images and videos with Seedance, Veo, Wan, Grok, GPT-Image and Nano Banana via one MCP.
Generate images, video, audio and short films with 140+ AI models from any MCP client.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for Higgsfield AI that enables unlimited-mode image, video, audio generation, uploads, and job management via multiple parallel accounts, using browser session authentication.3517MIT
- AlicenseAqualityBmaintenanceEnables any MCP client such as Claude, Cursor, Cline or Gemini CLI to generate Seedance 2.5, Seedance 2.0, MiniMax H3 and Veo 3.1 videos and still images from text or a reference image using your own account. It also exposes run-status polling and remaining-credit checks, with configurable duration, resolution, aspect ratio and audio.4136 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients to generate images and videos, synthesize text-to-speech audio, and clone or design custom voices. It also supports flexible output handling (URLs or local files) and multiple transport modes including stdio, REST, and SSE.635 npmMIT
- AlicenseBqualityCmaintenanceEnables any MCP-compatible AI agent to generate videos and images from text or reference frames, chain scenes into seamless multi-scene films with sound and speech, and download finished media with manifests and previews. It also exposes account status, plan limits, history and library management through confirm-gated, safe-by-default operations.2634MIT