内容
# 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.
MCP 市场