Bitrefill

Bitrefill MCP-Server (Beispielimplementierung)

Dies ist eine Beispiel- / Referenzimplementierung. Für den produktiven Einsatz verbinden Sie sich stattdessen mit dem offiziell gehosteten Bitrefill eCommerce MCP unter https://api.bitrefill.com/mcp. Es wird von Bitrefill gewartet, unterstützt OAuth und stellt dieselben Werkzeuge bereit, ohne dass Sie etwas ausführen, bereitstellen oder aktualisieren müssen.

Verwenden Sie dieses Repository, wenn Sie lernen möchten, wie ein Bitrefill MCP aufgebaut werden kann, es forken, erweitern oder eine angepasste Variante selbst hosten möchten, die auf der Bitrefill API v2 aufbaut.

Dieser Server umschließt die Bitrefill API v2 (https://api.bitrefill.com/v2) unter Verwendung von Authorization: Bearer ${BITREFILL_API_KEY}. Nur Request-Parameter werden mit Zod validiert; API-Antworten werden unverändert als JSON-Text zurückgegeben.

Das offizielle Remote-MCP verwenden (empfohlen für Produktion)

Das Bitrefill eCommerce MCP wird von Bitrefill gehostet und ist der empfohlene Weg zur Integration mit ChatGPT, Claude Desktop / Code, Cursor und jedem anderen MCP-kompatiblen Client.

• OAuth (empfohlen). Verweisen Sie Ihren Client auf:

  https://api.bitrefill.com/mcp
  

  Sie werden zu Bitrefill weitergeleitet, um sich anzumelden und den Zugriff zu autorisieren. Kein Umgang mit API-Schlüsseln erforderlich.

• API-Schlüssel. Hängen Sie Ihren Schlüssel von bitrefill.com/account/developers an:

  https://api.bitrefill.com/mcp/YOUR_API_KEY
  

Einrichtungsanleitungen pro Client: ChatGPT, Claude Desktop, Claude Code, Cursor.

Wann stattdessen dieses Repo verwenden

Führen Sie dieses lokale MCP nur aus, wenn Sie Folgendes benötigen:

• Eine funktionierende Referenzimplementierung eines Bitrefill MCP-Servers studieren.
• Es forken, um benutzerdefinierte Werkzeuge, Prompts, Validierung, Protokollierung oder Routing hinzuzufügen.
• Selbst-Hosting in einem privaten Netzwerk oder einer abgeschotteten Umgebung.
• Mit einem breiteren Satz von v2-Endpunkten experimentieren (dieses Beispiel stellt 18 Werkzeuge bereit, während das offizielle Remote-MCP bewusst einen kuratierten Satz von 7 bereitstellt; siehe eCommerce MCP).

Für alltägliche Anwendungsfälle wie „Geschenkkarten / eSIMs von meinem KI-Assistenten kaufen“ bevorzugen Sie den oben genannten gehosteten Server.

Konfiguration

1. Erstellen Sie einen API-Schlüssel: Bitrefill-Konto → Entwickler.
2. In der Umgebung setzen (oder .env für lokale Ausführungen):

BITREFILL_API_KEY=your_api_key_here

Wenn BITREFILL_API_KEY fehlt, werden keine Werkzeuge registriert (v2 erfordert Authentifizierung selbst für ping).

Werkzeuge (v1.0.0)

Werkzeug	API
search-products	GET /products/search (mit q) oder GET /products (Durchsuchen)
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}

Breaking Change gegenüber 0.x: Alte snake_case-Werkzeugnamen (search, create_invoice, unseal_order, ...) wurden entfernt. Verwenden Sie die oben genannten Namen. Es gibt kein unseal_order in v2; GET /orders/{id} gibt redemption_info zurück, wenn geliefert.

Ressourcen

• bitrefill://payment-methods: erlaubte payment_method-Zeichenketten für buy-products / create-esim-invoice
• bitrefill://category-slugs: B2B-category-Abfragewerte für Produktliste/-suche
• bitrefill://product-types: Produktfamilien-Schlüssel
• bitrefill://product-types/{productType}: Kategorie-Slugs pro Familie

Projektstruktur

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)

Entwicklung

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Smoke-Tests (nur das MCP dieses Repos)

Smoke-Tests starten immer den Server dieses Pakets (node build/index.js nach pnpm run build). Sie öffnen nicht https://api.bitrefill.com/mcp oder eine andere Remote-MCP-URL.

Empfohlen: MCP-Client im Prozess (stdio zu build/index.js):

pnpm run build
pnpm run smoke

Identisch mit pnpm run test-services (Alias).

Optional: MCP Inspector CLI, weiterhin nur gegen diesen Server:

pnpm run build
pnpm run smoke:inspector

Alle 18 Werkzeuge (Inspector CLI, Zusammenfassungszeilen, absichtlich Dummy-IDs):

pnpm run test:inspector:all-tools

Der Inspector verwendet --tool-arg key=value (für mehrere Schlüssel wiederholen), nicht einen einzelnen JSON-Blob. Für verschachtelte Daten verwenden Sie JSON im Wert, z. B.
--tool-arg 'products=[{"product_id":"x","value":10}]'.

Interaktive Benutzeroberfläche (nur lokaler Server):

pnpm run build
pnpm run inspector

Beispiele:

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

Client-Beispiele (selbst gehostetes Beispiel)

Erinnerung: Für die Produktion bevorzugen Sie das gehostete https://api.bitrefill.com/mcp (OAuth) gegenüber der unten stehenden stdio-Konfiguration.

Cursor / Claude-artige MCP-Konfiguration, übergeben Sie den Schlüssel in env:

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

Docker, z. B. -e BITREFILL_API_KEY=... oder --env-file .env.

Gehostetes Remote-MCP (keine Installation, empfohlen):

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

Dokumentation

• Bitrefill-Dokumentation (LLMs-Index)
• Bitrefill eCommerce MCP (gehostet): offizieller Remote-Server, empfohlen für die Produktion
• Einrichtungsanleitungen: ChatGPT, Claude, Cursor

Lizenz

MIT