higgsfield-mcp-server

Claude가 Higgsfield AI API를 통해 이미지와 비디오를 생성할 수 있게 해주는 원격 MCP 서버입니다 — 채팅에서 바로 사실적인 사진(Soul), 참조 기반 이미지(Popcorn), 비디오(Google Veo 3.1, Kling, ByteDance Seedance)를 생성할 수 있습니다.

노출된 도구

모든 생성 도구는 비동기 방식입니다. 즉시 request_id를 반환하고, 작업이 completed 상태가 될 때까지 higgsfield_check_status를 호출합니다(Claude가 자동으로 수행합니다).

Related MCP server: gemini-nano-banana-mcp

1. Higgsfield API 키 가져오기

1. https://cloud.higgsfield.ai에 접속하여 로그인하세요.

2. API 키를 생성하세요(Claude에게 도움을 요청한 후 이 글을 읽고 있다면 이미 생성했을 것입니다) — 그러면 API Key ID와 API Key Secret이 제공됩니다. 둘 다 복사하세요. 한 번만 표시됩니다.

2. 이 서버 배포하기 (무료 티어도 사용 가능)

Node 프로세스를 24/7 실행하고 HTTPS로 접근 가능한 환경이 필요합니다. 이 정도 규모의 서버에는 신용카드가 필요 없는 두 가지 무료 옵션이 있습니다:

옵션 A: Render.com

1. 이 폴더를 새 GitHub 저장소에 푸시하세요 (비공개 저장소도 괜찮습니다).

2. https://render.com에서 → New + → Web Service → 해당 저장소를 연결하세요.

3. 설정:

   • Runtime: Node

   • Build Command: npm install

   • Start Command: npm start

4. Environment에서 다음 세 가지 변수를 추가하세요:

   • HF_API_KEY_ID = 본인의 Higgsfield API Key ID

   • HF_API_KEY_SECRET = 본인의 Higgsfield API Key Secret

   • MCP_ACCESS_TOKEN = 직접 만든 임의의 긴 문자열 (예: 로컬에서 openssl rand -hex 32를 실행하거나 키보드를 40자 이상 마구 입력) — 이는 Claude가 서버와 통신하는 데 사용할 비밀번호이므로, 다른 사람이 본인의 Higgsfield 크레딧을 사용할 수 없게 합니다.

5. 배포하세요. Render는 https://higgsfield-mcp-server.onrender.com과 같은 URL을 제공합니다. MCP 엔드포인트는 해당 URL + /mcp입니다(예: https://higgsfield-mcp-server.onrender.com/mcp).

참고: Render의 무료 웹 서비스는 비활성 상태가 되면 절전 모드로 전환되며, 다음 요청 시 깨어나는 데 몇 초가 걸립니다 — 가끔 사용하는 용도에는 적합합니다.

옵션 B: Railway.app

같은 방식입니다. 이 GitHub 저장소에서 새 프로젝트를 만들고 동일한 세 가지 환경 변수를 설정하면 Railway가 npm start를 자동으로 감지합니다. https://higgsfield-mcp-server-production.up.railway.app과 같은 URL이 제공되며, 엔드포인트는 해당 URL + /mcp입니다.

3. Claude에 사용자 지정 커넥터로 추가하기

Claude(claude.ai / 데스크톱 앱)에서 → Settings → Connectors → Add custom connector를 선택하세요:

• 이름: Higgsfield

• URL: https://<your-deployed-url>/mcp

• 인증: Bearer token → 2단계에서 설정한 MCP_ACCESS_TOKEN 값을 붙여넣으세요.

채팅에서 이 커넥터를 활성화하면 Claude가 위 도구들을 호출할 수 있습니다.

로컬 테스트 (선택 사항)

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

서버는 http://localhost:3000/mcp(또는 $PORT)에서 수신 대기합니다.

보안 참고 사항

• HF_API_KEY_ID / HF_API_KEY_SECRET는 본인의 Higgsfield 계정 및 결제에 대한 완전한 액세스 권한을 제공합니다. 이 값들은 호스트의 환경 변수에만 존재합니다 — 절대 커밋하지 말고 URL에 넣지 마세요.

• MCP_ACCESS_TOKEN은 서버 URL을 발견한 임의의 사람이 본인의 Higgsfield 크레딧으로 콘텐츠를 생성하는 것을 막는 역할을 합니다. 비밀번호처럼 취급하세요.

• 모든 생성 호출은 요금제 가격에 따라 Higgsfield 크레딧을 사용합니다.