Higgsfield MCP API

Tiny local REST API for the official Higgsfield MCP endpoint.

Unofficial community project. Not affiliated with or endorsed by Higgsfield.

Why this exists

Higgsfield MCP is useful, but many apps and automation tools want a simple HTTP interface. This project wraps the official MCP tools as a local REST API so you can call Higgsfield from curl, Python, Node, n8n, Raycast, local dashboards, or your own scripts.

Highlights

Official MCP transport under the hood — no browser automation.
Simple local REST routes for balance, models, jobs, and image generation.
Device auth helper with redacted token output.
Optional .env token storage.
Optional local API key for REST routes.
Zero npm dependencies.
English and Korean documentation.

Requirements

Node.js 20+
A Higgsfield account with device auth approval

Quick start

git clone https://github.com/Noah3521/higgsfield-mcp-api.git
cd higgsfield-mcp-api
npm run check
node .\higgsfield-mcp-api.mjs auth-start

Open the printed verification_uri in your browser and approve the device flow.

Save the access token to .env without printing it:

node .\higgsfield-mcp-api.mjs auth-save --device-code "PASTE_DEVICE_CODE"

Start the API:

npm run serve

Default base URL:

http://127.0.0.1:8787

Generate an image

curl -X POST http://127.0.0.1:8787/generate/image `
  -H "Content-Type: application/json" `
  -d '{
    "model": "nano_banana_2",
    "prompt": "A small red cube on a clean white background",
    "count": 1,
    "ratio": "1:1",
    "params": { "resolution": "1k" }
  }'

Example response:

{
  "results": [
    {
      "id": "43afc8e6-5fe7-4590-9001-009c8055cfea",
      "status": "completed",
      "model": "nano_banana_2",
      "rawUrl": "https://...png",
      "minUrl": "https://...webp"
    }
  ]
}

REST endpoints

Full reference: docs/API.md / 한국어 API 문서

GET  /health
POST /auth/start
POST /auth/poll
GET  /balance
GET  /models
GET  /models/:id
GET  /jobs/:jobId?sync=true
POST /generate/image
GET  /tools
POST /tools/:name

CLI examples

node .\higgsfield-mcp-api.mjs balance
node .\higgsfield-mcp-api.mjs models --type image --limit 100
node .\higgsfield-mcp-api.mjs generate-image --model nano_banana_2 --prompt "red cube" --ratio 1:1 --resolution 1k

Observed concurrency behavior

Observed on an Ultimate annual account:

Rate limit reached: max 8 concurrent job(s) on ultimate (annual) plan.

The server maps this MCP response to HTTP 429.

Security notes

Bind to 127.0.0.1 by default.
Never commit .env, tokens, device codes, cookies, session values, or HAR files.
Set HIGGSFIELD_MCP_API_KEY if another local process can access the server.
MCP does not expose the web-only use_unlim flag, so image generation may consume credits.

Roadmap

More model-specific examples.
Dockerfile and compose example.
Typed client snippets for Python and TypeScript.
Optional local request queue for friendlier concurrency behavior.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

If this helped you, please consider starring the repo — it makes the project easier for other builders to discover.

MCP Servers