higgsfield-mcp-api

# Higgsfield MCP API [](https://nodejs.org/) [](https://github.com/Noah3521/higgsfield-mcp-api/actions/workflows/ci.yml) [](./LICENSE) [](./package.json) Tiny local REST API for the official Higgsfield MCP endpoint. English | [한국어](./README.ko.md) > 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 ```powershell 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: ```powershell node .\higgsfield-mcp-api.mjs auth-save --device-code "PASTE_DEVICE_CODE" ``` Start the API: ```powershell npm run serve ``` Default base URL: ```txt http://127.0.0.1:8787 ``` ## Generate an image ```powershell 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: ```json { "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](./docs/API.md) / [한국어 API 문서](./docs/API.ko.md) ```txt 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 ```powershell 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: ```txt 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](./CONTRIBUTING.md). If this helped you, please consider starring the repo — it makes the project easier for other builders to discover.