Bitrefill MCP Server

officiel

Achetez des cartes cadeaux, des eSIMs et des recharges téléphoniques. Payez par carte et crypto.

Documentation

Serveur MCP Bitrefill (Implémentation d'exemple)

Ceci est une implémentation d'exemple / de référence. Pour une utilisation en production, connectez-vous plutôt au MCP eCommerce Bitrefill officiel hébergé à l'adresse https://api.bitrefill.com/mcp. Il est maintenu par Bitrefill, prend en charge OAuth et expose les mêmes outils sans que vous ayez à exécuter, déployer ou mettre à jour quoi que ce soit.

Utilisez ce dépôt si vous souhaitez apprendre comment un MCP Bitrefill peut être construit, le forker, l'étendre ou auto-héberger une variante personnalisée basée sur l'API Bitrefill v2.

Ce serveur enveloppe l'API Bitrefill v2 (https://api.bitrefill.com/v2) en utilisant Authorization: Bearer ${BITREFILL_API_KEY}. Seuls les paramètres de requête sont validés avec Zod ; les réponses de l'API sont retournées sous forme de texte JSON inchangé.

Utiliser le MCP distant officiel (recommandé pour la production)

Le MCP eCommerce Bitrefill est hébergé par Bitrefill et constitue le moyen recommandé pour s'intégrer avec ChatGPT, Claude Desktop / Code, Cursor et tout autre client compatible MCP.

OAuth (recommandé). Pointez votre client vers :
```
https://api.bitrefill.com/mcp
```
Vous serez redirigé vers Bitrefill pour vous connecter et autoriser l'accès. Aucune gestion de clé API requise.
Clé API. Ajoutez votre clé depuis bitrefill.com/account/developers :
```
https://api.bitrefill.com/mcp/YOUR_API_KEY
```

Guides de configuration par client : ChatGPT, Claude Desktop, Claude Code, Cursor.

Quand utiliser ce dépôt à la place

Exécutez ce MCP local uniquement si vous avez besoin de :

Étudier une implémentation de référence fonctionnelle d'un serveur MCP Bitrefill.
Le forker pour ajouter des outils personnalisés, des invites, de la validation, de la journalisation ou du routage.
L'auto-héberger au sein d'un réseau privé ou d'un environnement isolé.
Expérimenter avec un ensemble plus large de points de terminaison v2 (cet exemple expose 18 outils, tandis que le MCP distant officiel expose intentionnellement un ensemble restreint de 7 ; voir MCP eCommerce).

Pour les cas d'usage quotidiens « acheter des cartes cadeaux / eSIM depuis mon assistant IA », préférez le serveur hébergé ci-dessus.

Configuration

Créez une clé API : Compte Bitrefill → Développeurs.
Définissez-la dans l'environnement (ou .env pour les exécutions locales) :

BITREFILL_API_KEY=your_api_key_here

Si BITREFILL_API_KEY est manquante, aucun outil n'est enregistré (la v2 nécessite une authentification même pour ping).

Outils (v1.0.0)

Outil	API
`search-products`	`GET /products/search` (avec `q`) ou `GET /products` (parcourir)
`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}`

Changement cassant par rapport à la v0.x : les anciens noms d'outils en snake_case (search, create_invoice, unseal_order, ...) ont été supprimés. Utilisez les noms ci-dessus. Il n'y a pas de unseal_order dans la v2 ; GET /orders/{id} retourne redemption_info une fois livré.

Ressources

bitrefill://payment-methods : chaînes payment_method autorisées pour buy-products / create-esim-invoice
bitrefill://category-slugs : valeurs de requête category B2B pour la liste/recherche de produits
bitrefill://product-types : clés de famille de produits
bitrefill://product-types/{productType} : slugs de catégorie par famille

Structure du projet

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)

Développement

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Tests de fumée (MCP de ce dépôt uniquement)

Les tests de fumée démarrent toujours le serveur de ce package (node build/index.js après pnpm run build). Ils n'ouvrent pas https://api.bitrefill.com/mcp ni aucune autre URL MCP distante.

Recommandé : client MCP en processus (stdio vers build/index.js) :

pnpm run build
pnpm run smoke

Identique à pnpm run test-services (alias).

Optionnel : CLI MCP Inspector, toujours uniquement contre ce serveur :

pnpm run build
pnpm run smoke:inspector

Les 18 outils (CLI Inspector, lignes de résumé, identifiants factices volontairement) :

pnpm run test:inspector:all-tools

L'Inspector utilise --tool-arg key=value (répéter pour plusieurs clés), pas un seul blob JSON. Pour les données imbriquées, utilisez JSON dans la valeur, par exemple
--tool-arg 'products=[{"product_id":"x","value":10}]'.

Interface utilisateur interactive (serveur local uniquement) :

pnpm run build
pnpm run inspector

Exemples :

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

Exemples clients (exemple auto-hébergé)

Rappel : pour la production, préférez le https://api.bitrefill.com/mcp hébergé (OAuth) plutôt que la configuration stdio ci-dessous.

Configuration MCP style Cursor / Claude, passez la clé dans env :

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

Docker, par exemple -e BITREFILL_API_KEY=... ou --env-file .env.

MCP distant hébergé (sans installation, recommandé) :

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

Documentation

Documentation Bitrefill (index llms)
MCP eCommerce Bitrefill (hébergé) : serveur distant officiel, recommandé pour la production
Guides de configuration : ChatGPT, Claude, Cursor

Licence

MIT