Bitrefill MCP Server

ทางการ

ซื้อบัตรของขวัญ e-sim และเติมเงินโทรศัพท์ จ่ายด้วยบัตรและคริปโต

เอกสาร

Bitrefill MCP Server (การใช้งานตัวอย่าง)

นี่คือการใช้งานตัวอย่าง / อ้างอิง สำหรับการใช้งานจริง ให้เชื่อมต่อกับ Bitrefill eCommerce MCP แบบโฮสต์อย่างเป็นทางการ ที่ https://api.bitrefill.com/mcp แทน ซึ่งดูแลโดย Bitrefill รองรับ OAuth และเปิดเผยเครื่องมือเดียวกันโดยที่คุณไม่ต้องรัน ติดตั้ง หรืออัปเดตอะไรเลย

ใช้ repository นี้หากคุณต้องการ เรียนรู้ว่า Bitrefill MCP สามารถสร้างขึ้นได้อย่างไร fork มัน ขยายความสามารถ หรือ โฮสต์เองในรูปแบบที่ปรับแต่ง บน Bitrefill API v2

เซิร์ฟเวอร์นี้ครอบคลุม Bitrefill API v2 (https://api.bitrefill.com/v2) โดยใช้ Authorization: Bearer ${BITREFILL_API_KEY} เฉพาะพารามิเตอร์ request เท่านั้นที่ตรวจสอบด้วย Zod; การตอบกลับจาก API จะถูกส่งคืนเป็นข้อความ JSON โดยไม่เปลี่ยนแปลง

ใช้ remote MCP อย่างเป็นทางการ (แนะนำสำหรับการใช้งานจริง)

Bitrefill eCommerce MCP โฮสต์โดย Bitrefill และเป็นวิธีที่แนะนำในการผสานรวมกับ ChatGPT, Claude Desktop / Code, Cursor และไคลเอนต์อื่น ๆ ที่รองรับ MCP

OAuth (แนะนำ) กำหนดให้ไคลเอนต์ของคุณไปที่:
```
https://api.bitrefill.com/mcp
```
คุณจะถูกเปลี่ยนเส้นทางไปยัง Bitrefill เพื่อลงชื่อเข้าใช้และอนุญาตการเข้าถึง ไม่ต้องจัดการ API key
API key เพิ่ม key ของคุณจาก bitrefill.com/account/developers:
```
https://api.bitrefill.com/mcp/YOUR_API_KEY
```

คู่มือการตั้งค่าต่อไคลเอนต์: ChatGPT, Claude Desktop, Claude Code, Cursor

เมื่อใดที่ควรใช้ repo นี้แทน

รัน MCP ภายในเครื่องนี้เฉพาะเมื่อคุณต้องการ:

ศึกษาการใช้งานอ้างอิงที่ทำงานได้ของเซิร์ฟเวอร์ Bitrefill MCP
Fork เพื่อเพิ่มเครื่องมือที่กำหนดเอง, prompts, การตรวจสอบ, การบันทึก หรือการกำหนดเส้นทาง
โฮสต์เองภายในเครือข่ายส่วนตัวหรือสภาพแวดล้อมที่แยกจากเครือข่าย
ทดลองกับชุด endpoints v2 ที่กว้างขึ้น (ตัวอย่างนี้เปิดเผย 18 เครื่องมือ ในขณะที่ remote MCP อย่างเป็นทางการตั้งใจเปิดเผยชุดที่คัดสรรแล้ว 7 รายการ; ดู eCommerce MCP)

สำหรับกรณีการใช้งานทั่วไป "ซื้อบัตรของขวัญ / eSIM จากผู้ช่วย AI ของฉัน" ให้เลือกใช้เซิร์ฟเวอร์ที่โฮสต์ด้านบน

การกำหนดค่า

สร้าง API key: บัญชี Bitrefill → Developers
ตั้งค่าใน environment (หรือ .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, ...) ถูกลบออก ใช้ชื่อด้านบน ไม่มี unseal_order ใน v2; GET /orders/{id} ส่งคืน redemption_info เมื่อจัดส่งแล้ว

ทรัพยากร

bitrefill://payment-methods: สตริง payment_method ที่อนุญาตสำหรับ buy-products / create-esim-invoice
bitrefill://category-slugs: ค่าคิวรี category แบบ B2B สำหรับรายการ/ค้นหาผลิตภัณฑ์
bitrefill://product-types: คีย์ตระกูลผลิตภัณฑ์
bitrefill://product-types/{productType}: slug หมวดหมู่ต่อตระกูล

โครงสร้างโปรเจกต์

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 ของ repo นี้)

การทดสอบควันจะเริ่มเซิร์ฟเวอร์ ของแพ็คเกจนี้ เสมอ (node build/index.js หลังจาก pnpm run build) พวกมัน ไม่ เปิด https://api.bitrefill.com/mcp หรือ URL MCP ระยะไกลอื่น ๆ

แนะนำ: ไคลเอนต์ 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, บรรทัดสรุป, รหัสจำลองโดยเจตนา):

pnpm run test:inspector:all-tools

Inspector ใช้ --tool-arg key=value (ทำซ้ำสำหรับหลายคีย์) ไม่ใช่ JSON blob เดียว สำหรับข้อมูลซ้อนกัน ให้ใช้ 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

ตัวอย่างไคลเอนต์ (ตัวอย่างที่โฮสต์เอง)

คำเตือน: สำหรับการใช้งานจริง ให้เลือกใช้ https://api.bitrefill.com/mcp แบบโฮสต์ (OAuth) แทนการกำหนดค่า stdio ด้านล่าง

การกำหนดค่า MCP แบบ Cursor / Claude ส่ง key ใน 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

remote MCP แบบโฮสต์ (ไม่ต้องติดตั้ง แนะนำ):

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

เอกสารประกอบ

เอกสาร Bitrefill (ดัชนี llms)
Bitrefill eCommerce MCP (โฮสต์): เซิร์ฟเวอร์ระยะไกลอย่างเป็นทางการ แนะนำสำหรับการใช้งานจริง
คู่มือการตั้งค่า: ChatGPT, Claude, Cursor

ใบอนุญาต

MIT