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: higgsfield-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 크레딧을 사용합니다.