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

1. Go to https://cloud.higgsfield.ai and sign in.
2. 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

1. Push this folder to a new GitHub repository (private is fine).
2. On https://render.com → New + → Web Service → connect that repo.
3. Settings:
   • Runtime: Node
   • Build Command: npm install
   • Start Command: npm start
4. 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.
5. 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.