Higgsfield MCP

MCP server for Higgsfield AI — generate images and videos with 16+ models through Claude, Cursor, or any MCP-compatible client.

Models

Image

Model	ID	Key Features
Nano Banana 2	nano-banana-2	Fast, reference images (up to 16), 1k/2k/4k
Nano Banana 1	nano-banana-1	Reference images, multi-ref
Soul v2	soul-v2	Stylized, 720p/1080p/2k
OpenAI Hazel	openai-hazel	GPT-Image-1.5, low/medium/high/4k

Video

Model	ID	Key Features
Kling 3.0	kling3	Best quality, start/end frames, sound, 720p/1080p, std/pro
Kling 3.0 Omni FLF	kling-o3-flf	First/last frame control
Kling 2.6	kling2-6	Balanced quality/cost
Kling 2.5 Turbo	kling2-5-turbo	Unlimited plan credits
Kling 2.1	kling	Budget option
Grok Video	grok	xAI video model
Wan 2.6	wan2-6	Open-source model
Wan 2.5	wan2-5-video	16:9 or 9:16 only
Seedance 1.5	seedance1-5	ByteDance latest
Seedance Pro	seedance	ByteDance pro
Veo 3	veo3	Google DeepMind
Sora 2	sora2-video	OpenAI, 4/8/12s durations
Image2Video	image2video	Requires input image

Tools

Tool	Description
higgsfield_generate_image	Generate images (returns job_id)
higgsfield_generate_video	Generate videos (returns job_id)
higgsfield_wait_for_job	Poll job(s) until complete, return result URLs
higgsfield_get_job	Check single job status (no polling)
higgsfield_list_jobs	List recent jobs with status and URLs
higgsfield_cancel_job	Cancel a running job
higgsfield_check_cost	Dry-run cost estimate for image generation
higgsfield_get_credits	Account balance and plan info
higgsfield_list_models	List all models with supported parameters
higgsfield_video_pricing	Static pricing reference
higgsfield_browser_status	Check Helm daemon connection
higgsfield_refresh_token	Manually set JWT token
higgsfield_refresh_credentials	Update Clerk session cookies for auto-refresh

Prerequisites

• Bun runtime
• A Higgsfield AI account (with credits)
• Helm daemon running with Chrome extension — used to get auth tokens from your browser session
• (Optional) curl-impersonate — improves reliability for GET requests. Set CURL_IMPERSONATE_BIN env var if the binary isn't in PATH. Falls back to native fetch if not installed.

Setup

# Clone
git clone https://github.com/jfikrat/higgsfield-mcp.git
cd higgsfield-mcp

# Install dependencies
bun install

# Run the server
bun run src/index.ts

Claude Code / Claude Desktop

Add to your MCP config (~/.claude/claude_desktop_config.json or MCP settings):

{
  "mcpServers": {
    "higgsfield": {
      "command": "bun",
      "args": ["run", "/path/to/higgsfield-mcp/src/index.ts"]
    }
  }
}

Authentication

The server authenticates via Clerk session tokens from your Higgsfield browser session. There are three methods (tried in order):

1. Auto-refresh — Clerk API refresh using saved session cookies (preferred)
2. Helm browser bridge — Extracts token from your logged-in Chrome session via Helm daemon
3. Manual — Paste a JWT token via higgsfield_refresh_token

First-time setup:

1. Log in to higgsfield.ai in Chrome
2. Make sure the Helm daemon is running (systemctl --user start helm-daemon)
3. Use higgsfield_browser_status to verify the connection
4. The server will auto-extract tokens from your browser session

If auto-refresh stops working (tokens expire ~every 7 days):

1. Open Chrome DevTools on higgsfield.ai
2. Copy cookies from the clerk.higgsfield.ai domain
3. Run higgsfield_refresh_credentials with the cookie string

Settings are stored at ~/.config/higgsfield-mcp/settings.json (permissions: 600).

Architecture

src/
├── index.ts          # MCP server entry point
├── models.ts         # Model metadata, validation, param builders
├── api.ts            # HTTP client (GET/POST/DELETE)
├── auth.ts           # Token management (Clerk refresh + browser fallback)
├── browser-post.ts   # Helm daemon bridge for browser-based POST
├── curl-fetch.ts     # curl-impersonate wrapper with native fallback
├── config.ts         # Secure settings storage (~/.config/higgsfield-mcp/)
├── tracker.ts        # Generation gallery tracker
└── tools/
    ├── account.ts    # Account, credits, model listing tools
    ├── image.ts      # Image generation tools
    └── video.ts      # Video generation + job polling tools

How It Works

Higgsfield uses DataDome bot protection that blocks non-browser POST requests. This server handles it with a two-layer approach:

• GET/DELETE requests go through curl-impersonate (or native fetch as fallback) with browser-like TLS fingerprints
• POST requests are routed through the Helm daemon, which executes fetch() inside your actual Chrome tab on higgsfield.ai — DataDome sees a real browser

License

MIT