Bitrefill MCP Server

resmi

Hediye kartları, e-simler ve telefon yüklemeleri satın alın. Kart ve kripto ile ödeme yapın.

Dokümantasyon

Bitrefill MCP Sunucusu (Örnek Uygulama)

Bu bir örnek / referans uygulamadır. Üretim kullanımı için, bunun yerine https://api.bitrefill.com/mcp adresindeki resmi barındırılan Bitrefill eCommerce MCP'ye bağlanın. Bitrefill tarafından yönetilir, OAuth'u destekler ve sizin çalıştırmanıza, dağıtmanıza veya herhangi bir şeyi güncellemenize gerek kalmadan aynı araçları sunar.

Bir Bitrefill MCP'nin nasıl oluşturulabileceğini öğrenmek, çatallamak, genişletmek veya Bitrefill API v2 üzerinde özelleştirilmiş bir varyantı kendi sunucunuzda barındırmak istiyorsanız bu depoyu kullanın.

Bu sunucu, Authorization: Bearer ${BITREFILL_API_KEY} kullanarak Bitrefill API v2'yi (https://api.bitrefill.com/v2) sarmalar. Yalnızca istek parametreleri Zod ile doğrulanır; API yanıtları değiştirilmeden JSON metni olarak döndürülür.

Resmi uzak MCP'yi kullanın (üretim için önerilir)

Bitrefill eCommerce MCP, Bitrefill tarafından barındırılır ve ChatGPT, Claude Desktop / Code, Cursor ve diğer MCP uyumlu istemcilerle entegrasyon için önerilen yoldur.

OAuth (önerilir). İstemcinizi şu adrese yönlendirin:
```
https://api.bitrefill.com/mcp
```
Oturum açmak ve erişime izin vermek için Bitrefill'e yönlendirileceksiniz. API anahtarı yönetimi gerekmez.
API anahtarı. bitrefill.com/account/developers adresinden anahtarınızı ekleyin:
```
https://api.bitrefill.com/mcp/YOUR_API_KEY
```

İstemci başına kurulum kılavuzları: ChatGPT, Claude Desktop, Claude Code, Cursor.

Bunun yerine bu depo ne zaman kullanılır

Bu yerel MCP'yi yalnızca şunlara ihtiyacınız varsa çalıştırın:

Bir Bitrefill MCP sunucusunun çalışan bir referans uygulamasını incelemek.
Özel araçlar, istemler, doğrulama, günlük kaydı veya yönlendirme eklemek için çatallamak.
Özel bir ağ veya hava boşluklu ortam içinde kendi sunucunuzda barındırmak.
Daha geniş bir v2 uç noktası seti ile denemeler yapmak (bu örnek 18 araç sunarken, resmi uzak MCP kasıtlı olarak seçilmiş 7 araçlık bir set sunar; bkz. eCommerce MCP).

Günlük "yapay zeka asistanımdan hediye kartları / eSIM'ler satın al" kullanım durumları için yukarıdaki barındırılan sunucuyu tercih edin.

Yapılandırma

Bir API anahtarı oluşturun: Bitrefill hesabı → Geliştiriciler.
Ortamda (veya yerel çalıştırmalar için .env) ayarlayın:

BITREFILL_API_KEY=your_api_key_here

Eğer BITREFILL_API_KEY eksikse, hiçbir araç kaydedilmez (v2, ping için bile kimlik doğrulama gerektirir).

Araçlar (v1.0.0)

Araç	API
`search-products`	`GET /products/search` (`q` ile) veya `GET /products` (göz at)
`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'e göre kırıcı değişiklik: eski snake_case araç adları (search, create_invoice, unseal_order, ...) kaldırıldı. Yukarıdaki adları kullanın. v2'de unseal_order yoktur; GET /orders/{id}, teslim edildiğinde redemption_info döndürür.

Kaynaklar

bitrefill://payment-methods: buy-products / create-esim-invoice için izin verilen payment_method dizeleri
bitrefill://category-slugs: ürün listesi/arama için B2B category sorgu değerleri
bitrefill://product-types: ürün ailesi anahtarları
bitrefill://product-types/{productType}: aile başına kategori slug'ları

Proje düzeni

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)

Geliştirme

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Duman testleri (yalnızca bu deponun MCP'si)

Duman testleri her zaman bu paketin sunucusunu başlatır (pnpm run build sonrası node build/index.js). https://api.bitrefill.com/mcp veya başka bir uzak MCP URL'sini açmazlar.

Önerilen: Süreç içi MCP istemcisi (build/index.js'e stdio):

pnpm run build
pnpm run smoke

pnpm run test-services ile aynı (takma ad).

İsteğe bağlı: MCP Inspector CLI, yine yalnızca bu sunucuya karşı:

pnpm run build
pnpm run smoke:inspector

18 aracın tümü (Inspector CLI, özet satırları, bilerek kullanılan sahte kimlikler):

pnpm run test:inspector:all-tools

Inspector, tek bir JSON blobu değil --tool-arg key=value kullanır (birden çok anahtar için tekrarlayın). İç içe veriler için değerde JSON kullanın, örn.
--tool-arg 'products=[{"product_id":"x","value":10}]'.

Etkileşimli kullanıcı arayüzü (yalnızca yerel sunucu):

pnpm run build
pnpm run inspector

Örnekler:

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

İstemci örnekleri (kendi sunucunuzda barındırılan örnek)

Hatırlatma: üretim için, aşağıdaki stdio yapılandırması yerine barındırılan https://api.bitrefill.com/mcp (OAuth) tercih edin.

Cursor / Claude tarzı MCP yapılandırması, anahtarı env içinde iletin:

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

Docker, örn. -e BITREFILL_API_KEY=... veya --env-file .env.

Barındırılan uzak MCP (kurulum yok, önerilir):

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

Dokümantasyon

Bitrefill dokümanları (llms indeksi)
Bitrefill eCommerce MCP (barındırılan): resmi uzak sunucu, üretim için önerilir
Kurulum kılavuzları: ChatGPT, Claude, Cursor

Lisans

MIT