Skillget

higgsfield-mcp-unified

mcp
Security Audit
Pass
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 96 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Local-first MCP server for the Higgsfield AI API: 85 typed image & video models (Seedance 2.5, Kling 3.0, Wan 3, Genjutsu, Soul, Cinema Studio), webhooks, cost estimates, Soul ID training. Opt-in web backend for Sora 2, Veo 3, Nano Banana.

README.md

higgsfield-mcp-unified

Unified Model Context Protocol (MCP) server for Higgsfield AI.
It puts 119 Higgsfield image and video models — Seedance 2.5, Kling 3.0 / O3, Wan 3, Genjutsu, Cinema Studio 4, Soul, Sora 2, Veo 3.x, Nano Banana, 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.

Backends

  • Official REST API (api.higgsfield.ai) — stable, KEY:SECRET auth. Default; rock-solid. Keys come from the Higgsfield dashboard.
  • 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=...        # key ID from the open.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?, extra_params?, webhook_url?) Submit a text-to-image / image-edit job (supports Soul character refs).
generate_video(model_id, prompt?, image_url?, …, extra_params?, webhook_url?) Submit a text-, image-, reference- or video-to-video job.
estimate_cost(model_id, params) Price a request (credits + USD) without submitting it.
list_model_presets(model_id, search?, size?, cursor?) Preset/option catalogs: Genjutsu Restyle styles, Marketing Studio Image presets, AI Influencer appearance options.
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 (2s → 10s backoff) until terminal. Returns images, video_url, audio_urls and artifacts (zip/mov/jsx/fbx/ply).
cancel_job(job_handle) Cancel a queued/in-progress job.
upload_image(path | data_base64, mime?, backend?) Upload a local image, WAV or MP4 and get a hosted URL (official backend by default).
create_character(name, image_urls, model_version?) / get_character / list_characters / delete_character Train and manage reusable Soul characters (v1 / v2 / cinema).
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, generated from docs.higgsfield.ai and cross-checked against the open.higgsfield.ai console): 85 endpoints — Soul / Soul V2 (text- and image-to-image) / Soul Cinema, AI Influencer, Ads Studio, Marketing Studio, Grok Image 2, Ideogram 4, Qwen Image 3, Recraft v4.1, Z-Image Turbo; Seedance 2.0 / 2.5, Kling 2.5 Turbo / 2.6 / 3.0 / O3 / Omni + Motion Control, Wan 2.6 / 2.7 / 3 / 3 Prime, Happy Horse 1.0 / 1.1, Genjutsu, Cinema Studio 4, MiniMax Hailuo 2.3 / H3, LTX 2.5, PixVerse v6, Grok Video 1.5.

Params beyond the named tool arguments (e.g. image_urls, video_url, generate_audio, negative_prompt, preset_id) go in extra_params; each model's supports and constraints list what it accepts.

Webhooks

Pass webhook_url (public HTTPS, official models only) to have Higgsfield POST the terminal result to your endpoint. It is sent as the documented hf_webhook query parameter. Deliveries use the envelope {request_id, status, error, payload} with outputs nested under payload, may be duplicated (dedupe by request_id + status), and are retried for up to two hours on network errors / 5xx. Polling with get_status remains the recovery path. See Webhooks.
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.

Reviews (0)

No results found