higgsfield-mcp

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