Bitrefill MCP Server

chính thức

Mua thẻ quà tặng, esim, nạp điện thoại. Thanh toán bằng thẻ và tiền điện tử.

Tài liệu

Bitrefill MCP Server (Triển khai Mẫu)

Đây là triển khai mẫu / tham khảo. Để sử dụng trong môi trường production, hãy kết nối tới Bitrefill eCommerce MCP chính thức được lưu trữ tại https://api.bitrefill.com/mcp. Nó được Bitrefill duy trì, hỗ trợ OAuth và cung cấp các công cụ tương tự mà bạn không cần phải chạy, triển khai hay cập nhật bất cứ thứ gì.

Sử dụng repository này nếu bạn muốn tìm hiểu cách một Bitrefill MCP có thể được xây dựng, fork nó, mở rộng nó, hoặc tự lưu trữ một biến thể tùy chỉnh dựa trên Bitrefill API v2.

Server này bao bọc Bitrefill API v2 (https://api.bitrefill.com/v2) sử dụng Authorization: Bearer ${BITREFILL_API_KEY}. Chỉ các tham số request được xác thực bằng Zod; phản hồi API được trả về dưới dạng văn bản JSON không thay đổi.

Sử dụng MCP từ xa chính thức (khuyến nghị cho production)

Bitrefill eCommerce MCP được lưu trữ bởi Bitrefill và là cách được khuyến nghị để tích hợp với ChatGPT, Claude Desktop / Code, Cursor và bất kỳ client tương thích MCP nào khác.

OAuth (khuyến nghị). Trỏ client của bạn tới:
```
https://api.bitrefill.com/mcp
```
Bạn sẽ được chuyển hướng đến Bitrefill để đăng nhập và ủy quyền truy cập. Không cần xử lý khóa API.
Khóa API. Thêm khóa của bạn từ bitrefill.com/account/developers:
```
https://api.bitrefill.com/mcp/YOUR_API_KEY
```

Hướng dẫn thiết lập cho từng client: ChatGPT, Claude Desktop, Claude Code, Cursor.

Khi nào nên sử dụng repo này thay thế

Chỉ chạy MCP cục bộ này nếu bạn cần:

Nghiên cứu một triển khai tham khảo hoạt động của một Bitrefill MCP server.
Fork nó để thêm các công cụ, prompt, xác thực, ghi log hoặc định tuyến tùy chỉnh.
Tự lưu trữ trong mạng nội bộ hoặc môi trường biệt lập.
Thử nghiệm với một tập hợp rộng hơn các endpoint v2 (mẫu này cung cấp 18 công cụ, trong khi MCP từ xa chính thức cố ý cung cấp một tập hợp được chọn lọc gồm 7 công cụ; xem eCommerce MCP).

Đối với các trường hợp sử dụng hàng ngày "mua thẻ quà tặng / eSIM từ trợ lý AI của tôi", hãy ưu tiên server được lưu trữ ở trên.

Cấu hình

Tạo một khóa API: Tài khoản Bitrefill → Developers.
Thiết lập trong môi trường (hoặc .env cho các lần chạy cục bộ):

BITREFILL_API_KEY=your_api_key_here

Nếu BITREFILL_API_KEY bị thiếu, không có công cụ nào được đăng ký (v2 yêu cầu xác thực ngay cả đối với ping).

Công cụ (v1.0.0)

Công cụ	API
`search-products`	`GET /products/search` (với `q`) hoặc `GET /products` (duyệt)
`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}`

Thay đổi không tương thích so với 0.x: các tên công cụ snake_case cũ (search, create_invoice, unseal_order, ...) đã bị loại bỏ. Sử dụng các tên ở trên. Không có unseal_order trong v2; GET /orders/{id} trả về redemption_info khi được giao.

Tài nguyên

bitrefill://payment-methods: các chuỗi payment_method được phép cho buy-products / create-esim-invoice
bitrefill://category-slugs: các giá trị truy vấn category B2B cho danh sách/tìm kiếm sản phẩm
bitrefill://product-types: khóa họ sản phẩm
bitrefill://product-types/{productType}: slug danh mục cho mỗi họ

Bố cục dự án

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)

Phát triển

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Kiểm thử khói (chỉ dành cho MCP của repo này)

Kiểm thử khói luôn khởi động server của gói này (node build/index.js sau pnpm run build). Chúng không mở https://api.bitrefill.com/mcp hoặc bất kỳ URL MCP từ xa nào khác.

Khuyến nghị: MCP client trong cùng tiến trình (stdio tới build/index.js):

pnpm run build
pnpm run smoke

Tương tự như pnpm run test-services (bí danh).

Tùy chọn: MCP Inspector CLI, vẫn chỉ chạy với server này:

pnpm run build
pnpm run smoke:inspector

Tất cả 18 công cụ (Inspector CLI, dòng tóm tắt, id giả có chủ đích):

pnpm run test:inspector:all-tools

Inspector sử dụng --tool-arg key=value (lặp lại cho nhiều khóa), không phải một khối JSON đơn lẻ. Đối với dữ liệu lồng nhau, sử dụng JSON trong giá trị, ví dụ:
--tool-arg 'products=[{"product_id":"x","value":10}]'.

Giao diện tương tác (chỉ server cục bộ):

pnpm run build
pnpm run inspector

Ví dụ:

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

Ví dụ về client (mẫu tự lưu trữ)

Nhắc nhở: đối với production, ưu tiên https://api.bitrefill.com/mcp được lưu trữ (OAuth) hơn cấu hình stdio bên dưới.

Cấu hình MCP kiểu Cursor / Claude, truyền khóa trong env:

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

Docker, ví dụ: -e BITREFILL_API_KEY=... hoặc --env-file .env.

MCP từ xa được lưu trữ (không cần cài đặt, khuyến nghị):

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

Tài liệu

Tài liệu Bitrefill (chỉ mục llms)
Bitrefill eCommerce MCP (được lưu trữ): server từ xa chính thức, khuyến nghị cho production
Hướng dẫn thiết lập: ChatGPT, Claude, Cursor

Giấy phép

MIT