Higgsfield MCP

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

Models

Image

Video

Tools

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