Bitrefill

공식

선불카드, eSIM, 휴대폰 충전을 구매하세요. 카드와 암호화폐로 결제할 수 있습니다.

GitHub

Bitrefill MCP(으)로 무엇을 할 수 있나요?

기프트 카드 및 eSIM 검색 — search-products를 사용하여 키워드로 사용 가능한 제품을 찾거나 전체 카탈로그를 탐색하세요.
제품 세부 정보 확인 — product-details를 사용하여 특정 제품의 가격, 액면가 및 지역 정보를 조회하세요.
기프트 카드 또는 eSIM 구매 — buy-products 또는 create-esim-invoice를 통해 구매를 위한 인보이스를 생성하세요.
인보이스 결제 — pay-invoice 또는 pay-esim-invoice로 인보이스를 결제하여 보류 중인 구매를 완료하세요.
주문 또는 인보이스 조회 — get-order-by-id 또는 get-invoice-by-id를 사용하여 상태 및 사용 정보를 가져오세요.
계정 잔액 확인 — get-account-balance로 현재 Bitrefill 잔액을 조회하세요.

문서

Bitrefill MCP 서버 (샘플 구현)

이것은 샘플 / 참조 구현입니다. 프로덕션 용도로는 공식 호스팅 Bitrefill eCommerce MCP를 https://api.bitrefill.com/mcp에서 연결하세요. Bitrefill이 유지 관리하며, OAuth를 지원하고, 여러분이 실행, 배포, 업데이트할 필요 없이 동일한 도구를 노출합니다.

이 저장소는 Bitrefill MCP가 어떻게 구축될 수 있는지 배우거나, 포크하거나, 확장하거나, Bitrefill API v2 위에 커스터마이즈된 변형을 자체 호스팅하려는 경우에 사용하세요.

이 서버는 Bitrefill API v2(https://api.bitrefill.com/v2)를 **Authorization: Bearer ${BITREFILL_API_KEY}**를 사용하여 래핑합니다. 요청 매개변수만 Zod로 검증되며, API 응답은 JSON 텍스트로 변경 없이 반환됩니다.

공식 원격 MCP 사용 (프로덕션 권장)

Bitrefill eCommerce MCP는 Bitrefill이 호스팅하며, ChatGPT, Claude Desktop / Code, Cursor 및 기타 MCP 호환 클라이언트와 통합하는 데 권장되는 방법입니다.

OAuth (권장). 클라이언트를 다음으로 지정하세요:
```
https://api.bitrefill.com/mcp
```
Bitrefill로 리디렉션되어 로그인하고 액세스 권한을 부여합니다. API 키 처리가 필요하지 않습니다.
API 키. bitrefill.com/account/developers에서 키를 추가하세요:
```
https://api.bitrefill.com/mcp/YOUR_API_KEY
```

클라이언트별 설정 가이드: ChatGPT, Claude Desktop, Claude Code, Cursor.

이 저장소를 대신 사용해야 하는 경우

다음과 같은 경우에만 이 로컬 MCP를 실행하세요:

Bitrefill MCP 서버의 작동하는 참조 구현을 연구해야 할 때.
사용자 정의 도구, 프롬프트, 검증, 로깅 또는 라우팅을 추가하기 위해 포크해야 할 때.
사설 네트워크 또는 에어갭 환경 내에서 자체 호스팅해야 할 때.
더 넓은 범위의 v2 엔드포인트를 실험해야 할 때 (이 샘플은 18개의 도구를 노출하는 반면, 공식 원격 MCP는 의도적으로 선별된 7개의 도구를 노출합니다. eCommerce MCP 참조).

"AI 어시스턴트에서 기프트 카드 / eSIM 구매"와 같은 일상적인 사용 사례에는 위의 호스팅 서버를 선호하세요.

설정

API 키 생성: Bitrefill 계정 → 개발자.
환경 변수에 설정 (또는 로컬 실행 시 .env):

BITREFILL_API_KEY=your_api_key_here

BITREFILL_API_KEY이 누락된 경우, 도구가 등록되지 않습니다 (v2는 ping에도 인증이 필요합니다).

도구 (v1.0.0)

도구	API
`search-products`	`GET /products/search` (`q` 사용) 또는 `GET /products` (찾아보기)
`product-details`	`GET /products/{id}`
`buy-products`	`POST /invoices`
`get-invoice-by-id`	`GET /invoices/{id}`
`get-order-by-id`	`GET /orders/{id}`
`list-invoices`	`GET /invoices`
`list-orders`	`GET /orders`
`pay-invoice`	`POST /invoices/{id}/pay`
`get-account-balance`	`GET /accounts/balance`
`check-phone-number`	`GET /check_phone_number`
`ping`	`GET /ping`
`list-esim-products`	`GET /products/esims`
`get-esim-product`	`GET /products/esims/{id}`
`create-esim-invoice`	`POST /esims`
`get-esim-invoice`	`GET /esims/invoice/{id}`
`pay-esim-invoice`	`POST /esims/invoice/{id}/pay`
`list-esims`	`GET /esims`
`get-esim`	`GET /esims/{id}`

0.x 대비 주요 변경 사항: 이전 snake_case 도구 이름(search, create_invoice, unseal_order, ...)이 제거되었습니다. 위의 이름을 사용하세요. v2에는 unseal_order이 없습니다. GET /orders/{id}는 배송 시 redemption_info을 반환합니다.

리소스

bitrefill://payment-methods: buy-products / create-esim-invoice에 허용되는 payment_method 문자열
bitrefill://category-slugs: 제품 목록/검색을 위한 B2B category 쿼리 값
bitrefill://product-types: 제품군 키
bitrefill://product-types/{productType}: 제품군별 카테고리 슬러그

프로젝트 레이아웃

src/
  index.ts
  types/api.ts          # Optional TS shapes for API JSON (not validated at runtime)
  constants/            # payment_method list, category slugs
  handlers/             # resources.ts, tools.ts
  schemas/              # Zod: inputs only
  services/             # API calls (search, products, invoices, orders, esims, misc)
  utils/api/            # base (BitrefillApiError), authenticated (Bearer v2)

개발

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

스모크 테스트 (이 저장소의 MCP만 해당)

스모크 테스트는 항상 이 패키지의 서버를 시작합니다 (pnpm run build 이후 node build/index.js). https://api.bitrefill.com/mcp 또는 다른 원격 MCP URL을 열지 않습니다.

권장: MCP 클라이언트 인프로세스 (stdio에서 build/index.js로):

pnpm run build
pnpm run smoke

pnpm run test-services와 동일 (별칭).

선택 사항: MCP Inspector CLI, 여전히 이 서버에 대해서만:

pnpm run build
pnpm run smoke:inspector

18개 도구 모두 (Inspector CLI, 요약 줄, 의도적인 더미 ID):

pnpm run test:inspector:all-tools

Inspector는 단일 JSON blob이 아닌 --tool-arg key=value (여러 키에 대해 반복)을 사용합니다. 중첩된 데이터의 경우 값에 JSON을 사용하세요. 예:
--tool-arg 'products=[{"product_id":"x","value":10}]'.

대화형 UI (로컬 서버만 해당):

pnpm run build
pnpm run inspector

예시:

pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name ping
pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name product-details --tool-arg id=test-gift-card-code

클라이언트 예시 (자체 호스팅 샘플)

알림: 프로덕션의 경우 아래 stdio 구성보다 호스팅된 https://api.bitrefill.com/mcp (OAuth)를 선호하세요.

Cursor / Claude 스타일 MCP 구성, env에 키 전달:

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "env": {
        "BITREFILL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker, 예: -e BITREFILL_API_KEY=... 또는 --env-file .env.

호스팅된 원격 MCP (설치 불필요, 권장):

{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp"
    }
  }
}

문서

Bitrefill 문서 (llms 색인)
Bitrefill eCommerce MCP (호스팅): 공식 원격 서버, 프로덕션 권장
설정 가이드: ChatGPT, Claude, Cursor

라이선스

MIT