Skip to main content
Glama
higgsfield-mcp-unified

higgsfield-mcp-unified

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:SECRET auth. 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 server

Configure

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.ai surface 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 __client cookie, but Clerk rotates that cookie too (~7 days). When it rotates, paste a new one.

  • Bot protection. fnf.higgsfield.ai sits 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

list_models(kind?, backend?, include_unverified?)

The model registry. Inferred (unverified) models are hidden unless include_unverified.

recommend_model(intent, kind?, top?)

Rank models for a described goal (local, no API call).

validate_params(model_id, params)

Check params against a model's supported set before submitting.

preflight_check()

Validate auth + reachability for both backends without spending a generation.

generate_image(model_id, prompt, …, soul_id?)

Submit a text-to-image / image-edit job (supports Soul character refs).

generate_video(model_id, prompt, image_url?, …)

Submit a text-to-video / image-to-video job.

generate_batch(requests[])

Fan out multiple image/video submits concurrently.

generate_speech_video(image_url, audio_url, prompt?)

Talking-head video from a face image + WAV audio.

get_status(job_handle) / subscribe(job_handle)

Poll, or long-poll until terminal, with output URLs.

cancel_job(job_handle)

Cancel a queued/in-progress job.

upload_image(path | data_base64, backend?)

Upload a local image and get a hosted URL.

create_character / get_character / list_characters / delete_character

Train and manage reusable Soul characters.

list_soul_styles() / list_motions()

Soul style and DOP motion presets, by name.

get_balance()

Available credits + plan (official backend).

list_jobs(page?, page_size?)

Recent generations (history).

Resources & prompts

  • Resources: higgsfield://models (full catalog) and higgsfield://models/{kind} — subscribe to the catalog instead of repeatedly calling list_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 unless include_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 src

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

License

MIT — see LICENSE.

Available Tools

20 tools
cancel_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

    B3.3/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP server for Higgsfield AI that enables unlimited-mode image, video, audio generation, uploads, and job management via multiple parallel accounts, using browser session authentication.
      35
      17
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      4
      136 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      26
      34
      MIT