Bitrefill MCP Service Adapter

This Node.js/TypeScript utility acts as a bridge, implementing the Model Context Protocol (MCP) to bring Bitrefill's extensive catalog of digital goods (like prepaid vouchers, mobile credits, and eSIMs) directly into the operational context of large language models (LLMs).

Operational Flow

The application operates as a standard process communicating over standard input/output (stdio) as mandated by the MCP specification. It registers specialized function definitions (tools) and data endpoints (resources) that AI assistants can invoke to perform actions:

1. Registration: Announces available resources and tools upon initialization.
2. Tool Invocation: Receives structured requests from the LLM client.
3. API Translation: Translates MCP calls into appropriate external Bitrefill API requests.
4. Response Structuring: Formats the external API results into validated JSON adhering to the MCP response schema.

Internal Structure Overview

src/
├── index.ts                # Bootstrap and main execution module
├── constants/              # Immutable configuration data
│   ├── categories.ts       # Predefined product taxonomy listings
│   └── payment_methods.ts  # Supported payment rail enumerations
├── handlers/               # Core MCP request processing logic
│   ├── resources.ts        # Logic for serving resource metadata
│   └── tools.ts            # Implementations for all exposed functionalities
├── schemas/                # Zod/JSON Schema definitions for validation
│   ├── detail.ts           # Schemas for retrieving specific product attributes
│   ├── invoice.ts          # Schemas governing invoice creation/retrieval
│   ├── misc.ts             # Auxiliary data structure definitions
│   ├── order.ts            # Schemas for post-purchase operations (tracking, redemption)
│   └── search.ts           # Schemas defining query parameters and catalog results
├── services/               # Abstractions layer for external communication
│   ├── invoices.ts         # Service methods for handling billing documents
│   ├── misc.ts             # Utility API interactions
│   ├── orders.ts           # Service methods for order lifecycle management
│   ├── products.ts         # Service methods for fetching granular product specifications
│   └── search.ts           # Service methods dedicated to catalog exploration
└── utils/                  # Support utilities
    ├── index.ts            # Cross-cutting concerns (logging, exception management)
    └── api/
        ├── authenticated.ts # Client for authenticated endpoints
        ├── base.ts         # Generic HTTP client foundation
        └── public.ts       # Client for unauthenticated endpoints

Exposed Functionality (Tools & Resources)

Discoverable Data Endpoints (Resources)

• bitrefill://product-types - Enumerates all high-level product groups supported.
• bitrefill://categories/{type} - Provides categorical breakdowns within a given product type (e.g., retrieving all 'Gaming' subcategories).

Actionable Capabilities (Tools)

• search - Locates available digital assets. Requires: query (e.g., brand name or wildcard ''). Optional:* Filters by region (country), locale (language), pagination parameters.

• detail - Fetches comprehensive specifications for a known product identifier. Requires: id.

• categories - Retrieves the complete, normalized map of product types and their associated categories.

• create_invoice - Initiates a purchase transaction. Requires: A list of desired items (products array, specifying product_id, quantity, etc.) and a settlement mechanism (payment_method: 'balance', 'bitcoin', or 'lightning').

• get_invoices - Lists previously generated invoices, supporting time-based filtering.

• get_invoice - Fetches the status and details of a single invoice. Requires: id.

• pay_invoice - Attempts to settle an outstanding invoice, typically restricted to internal account balance settlement.

• get_orders - Retrieves transaction history, supporting cursor-based pagination.

• get_order - Fetches the status of a finalized transaction. Requires: id.

• unseal_order - Reveals sensitive fulfillment data (like gift card codes) for a completed order. Requires: id.

• get_account_balance - Queries the current available balance within the linked Bitrefill account.

• ping - A simple health check to confirm external API connectivity.

Configuration Prerequisite

Authentication via the Bitrefill API is mandatory for all transactional tools (create_invoice through get_account_balance). Read-only discovery tools (search, categories, detail) function without credentials.

1. Secure a developer API key pair (ID and Secret) from the official Bitrefill developer portal.
2. Establish a .env configuration file mirroring .env.example in the execution root.
3. Populate the following environment variables: BITREFILL_API_SECRET=your_secret_key BITREFILL_API_ID=your_identifier

If credentials are absent, transactional tools will be dynamically excluded from the advertised toolset.

Development Workflow

Install dependencies:

npm install

Compile source code:

npm run build

Enable hot-reloading during iteration:

npm run watch

Diagnostics

Debugging stdio communication can be complex. We strongly recommend utilizing the official MCP Inspector package script for interface visualization:

npm run inspector

This command generates a local URL allowing you to monitor the bidirectional message flow via a browser interface.

Deployment Instructions

Automated Installation via Smithery

For seamless integration into Claude Desktop via Smithery:

npx -y @smithery/cli install @bitrefill/bitrefill-mcp-server --client claude

Claude Desktop Configuration

Update the configuration file located at: - MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Cline Extension Setup

Navigate to Cline extension settings -> 'MCP Servers' tab -> 'Configure MCP Servers':

{
  "mcpServers": {
    "github.com/bitrefill/bitrefill-mcp-server": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "disabled": false,
      "autoApprove": ["search", "detail", "categories"],
      "env": {
        "BITREFILL_API_ID": "your_api_id_here",
        "BITREFILL_API_SECRET": "your_api_key_here"
      }
    }
  }
}

Cursor IDE Integration

1. Access Cursor settings.
2. Navigate to the 'Features' section.
3. Locate the 'MCP Servers' area and select 'Add new MCP Server'.
4. Set the Type to "command" and input the execution string:

npx -y bitrefill-mcp-server

1. If using transaction capabilities, specify the required environment secrets in the designated field.

Containerized Execution (Docker)

First, build the deployment image:

docker build -t refill-adapter .

Then, execute the container, injecting necessary credentials:

docker run -e BITREFILL_API_SECRET=secret -e BITREFILL_API_ID=id refill-adapter

For source code volume mounting during development:

docker run -v $(pwd):/app --env-file .env refill-adapter