Higgsfield MCP API

Tiny local REST API for the official Higgsfield MCP endpoint.

English | 한국어

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.