Servidor MCP de Bitrefill (Implementación de ejemplo)

Esta es una implementación de ejemplo / referencia. Para uso en producción, conéctese al MCP de comercio electrónico oficial alojado de Bitrefill en https://api.bitrefill.com/mcp en su lugar. Está mantenido por Bitrefill, admite OAuth y expone las mismas herramientas sin que usted tenga que ejecutar, implementar o actualizar nada.

Utilice este repositorio si desea aprender cómo se puede construir un MCP de Bitrefill, hacer un fork, extenderlo o alojar usted mismo una variante personalizada sobre la API v2 de Bitrefill.

Este servidor envuelve la API v2 de Bitrefill (https://api.bitrefill.com/v2) usando Authorization: Bearer ${BITREFILL_API_KEY}. Solo los parámetros de solicitud se validan con Zod; las respuestas de la API se devuelven como texto JSON sin cambios.

Utilice el MCP remoto oficial (recomendado para producción)

El MCP de comercio electrónico de Bitrefill está alojado por Bitrefill y es la forma recomendada de integrarse con ChatGPT, Claude Desktop / Code, Cursor y cualquier otro cliente compatible con MCP.

• OAuth (recomendado). Apunte su cliente a:

  https://api.bitrefill.com/mcp

  Será redirigido a Bitrefill para iniciar sesión y autorizar el acceso. No se requiere manejo de claves API.

• Clave API. Adjunte su clave desde bitrefill.com/account/developers:

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

Guías de configuración por cliente: ChatGPT, Claude Desktop, Claude Code, Cursor.

Related MCP server: agentstorefront-mcp

Cuándo usar este repositorio en su lugar

Ejecute este MCP local solo si necesita:

• Estudiar una implementación de referencia funcional de un servidor MCP de Bitrefill.

• Hacer un fork para añadir herramientas personalizadas, prompts, validación, registro o enrutamiento.

• Alojarlo usted mismo dentro de una red privada o un entorno sin conexión a internet (air-gapped).

• Experimentar con un conjunto más amplio de endpoints de la v2 (esta muestra expone 18 herramientas, mientras que el MCP remoto oficial expone intencionalmente un conjunto curado de 7; vea eCommerce MCP).

Para casos de uso cotidianos de "comprar tarjetas de regalo / eSIMs desde mi asistente de IA", prefiera el servidor alojado anteriormente.

Configuración

1. Cree una clave API: Cuenta de Bitrefill → Desarrolladores.

2. Establézcala en el entorno (o en .env para ejecuciones locales):

BITREFILL_API_KEY=your_api_key_here

Si falta BITREFILL_API_KEY, no se registran herramientas (la v2 requiere autenticación incluso para ping).

Herramientas (v1.0.0)

Cambio importante respecto a 0.x: se eliminaron los nombres de herramientas antiguos en snake_case (search, create_invoice, unseal_order, ...). Use los nombres anteriores. No existe unseal_order en la v2; GET /orders/{id} devuelve redemption_info cuando se entrega.

Recursos

• bitrefill://payment-methods: cadenas de payment_method permitidas para buy-products / create-esim-invoice

• bitrefill://category-slugs: valores de consulta de category B2B para listas/búsquedas de productos

• bitrefill://product-types: claves de familia de productos

• bitrefill://product-types/{productType}: slugs de categoría por familia

Estructura del proyecto

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)

Desarrollo

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Pruebas de humo (solo para el MCP de este repositorio)

Las pruebas de humo siempre inician el servidor de este paquete (node build/index.js después de pnpm run build). No abren https://api.bitrefill.com/mcp ni ninguna otra URL de MCP remoto.

Recomendado: Cliente MCP en proceso (stdio a build/index.js):

pnpm run build
pnpm run smoke

Igual que pnpm run test-services (alias).

Opcional: CLI de MCP Inspector, solo contra este servidor:

pnpm run build
pnpm run smoke:inspector

Las 18 herramientas (CLI de Inspector, líneas de resumen, ids ficticios a propósito):

pnpm run test:inspector:all-tools

El Inspector utiliza --tool-arg key=value (repetir para múltiples claves), no un único blob JSON. Para datos anidados, use JSON en el valor, p. ej. --tool-arg 'products=[{"product_id":"x","value":10}]'.

Interfaz de usuario interactiva (solo servidor local):

pnpm run build
pnpm run inspector

Ejemplos:

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

Ejemplos de cliente (muestra autoalojada)

Recordatorio: para producción, prefiera el https://api.bitrefill.com/mcp alojado (OAuth) sobre la configuración de stdio a continuación.

Configuración de MCP estilo Cursor / Claude, pase la clave en env:

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

Docker, p. ej. -e BITREFILL_API_KEY=... o --env-file .env.

MCP remoto alojado (sin instalación, recomendado):

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

Documentación

• Documentación de Bitrefill (índice llms)

• MCP de comercio electrónico de Bitrefill (alojado): servidor remoto oficial, recomendado para producción

• Guías de configuración: ChatGPT, Claude, Cursor

Licencia

MIT