higgsfield-mcp-server

Remote MCP server that lets Claude generate images and videos through the Higgsfield AI API — photorealistic photos (Soul), reference-guided images (Popcorn), and video (Google Veo 3.1, Kling, ByteDance Seedance) — directly from chat.

Tools exposed

Tool	What it does
`higgsfield_generate_photo`	Text-to-image, photorealistic (Soul/Standard)
`higgsfield_generate_image_with_references`	Text-to-image with up to 8 reference photos (Popcorn/Auto)
`higgsfield_generate_video`	Text/image/frame/reference-to-video via Google Veo 3.1
`higgsfield_generate_video_kling`	Cinematic video via Kling v2.1 / v2.5
`higgsfield_generate_video_seedance`	Fast/cheap video via ByteDance Seedance
`higgsfield_check_status`	Poll a generation job until it's done
`higgsfield_cancel_request`	Cancel a queued job
`higgsfield_list_models`	List every available endpoint (incl. ones only reachable via raw_request)
`higgsfield_raw_request`	Call any other Higgsfield endpoint (Soul character/reference, FLUX Kontext, MiniMax Hailuo, DOP)

All generation tools are asynchronous: they return a request_id immediately; call higgsfield_check_status (Claude will do this automatically) until the job is completed.

1. Get your Higgsfield API keys

Go to https://cloud.higgsfield.ai and sign in.
Create an API key (you did this already if you're reading this after asking Claude for help) — you get an API Key ID and an API Key Secret. Copy both, they're shown only once.

2. Deploy this server (free tier works)

You need somewhere that keeps a Node process running 24/7 and reachable over HTTPS. Two free options that need no credit card for a small server like this:

Option A: Render.com

Push this folder to a new GitHub repository (private is fine).
On https://render.com → New + → Web Service → connect that repo.
Settings:
- Runtime: Node
- Build Command: npm install
- Start Command: npm start
Under Environment, add these three variables:
- HF_API_KEY_ID = your Higgsfield API Key ID
- HF_API_KEY_SECRET = your Higgsfield API Key Secret
- MCP_ACCESS_TOKEN = any long random string you make up (e.g. run openssl rand -hex 32 locally, or just mash the keyboard for 40+ characters) — this is the password Claude will use to talk to your server, so nobody else can spend your Higgsfield credits.
Deploy. Render gives you a URL like https://higgsfield-mcp-server.onrender.com. Your MCP endpoint is that URL + /mcp, e.g. https://higgsfield-mcp-server.onrender.com/mcp.

Note: Render's free web services sleep after inactivity and take a few seconds to wake up on the next request — fine for occasional use.

Option B: Railway.app

Same idea: new project from this GitHub repo, set the same three environment variables, Railway auto-detects npm start. You get a URL like https://higgsfield-mcp-server-production.up.railway.app, endpoint is that + /mcp.

3. Add it to Claude as a custom connector

In Claude (claude.ai / desktop app) → Settings → Connectors → Add custom connector:

Name: Higgsfield
URL: https://<your-deployed-url>/mcp
Authentication: Bearer token → paste the MCP_ACCESS_TOKEN value you set in step 2.

Enable it for your chat, and Claude will be able to call the tools above.

Local testing (optional)

cp .env.example .env   # fill in real values
npm install
npm start

The server listens on http://localhost:3000/mcp (or $PORT).

Security notes

HF_API_KEY_ID / HF_API_KEY_SECRET give full access to your Higgsfield account and billing. They live only in the host's environment variables — never commit them, never put them in the URL.
MCP_ACCESS_TOKEN is what stops a random person who finds your server URL from generating content on your Higgsfield credits. Treat it like a password.
Every generation call spends Higgsfield credits per your plan's pricing.