bitrefill

Bitrefill MCP Server exposes Bitrefill services to AI assistants via the Model Context Protocol. It provides a set of resources and tools that allow you to search for gift cards, mobileTopups, esims, and other Bitrefill offerings, as well as retrieve detailed product information and manage invoices and orders when API credentials are provided. The server runs as a standalone process and communicates over stdio, making it compatible with Claude Desktop, Cline, Cursor, and other MCP clients. Tools include search (to query products), detail (to fetch product info), categories (to obtain the full product types map), and a suite of invoice and order related actions (create_invoice, get_invoices, get_invoice, pay_invoice, get_orders, get_order, unseal_order, get_account_balance, ping). If you supply your Bitrefill API credentials, create_invoice becomes available; otherwise only read-only tools remain accessible.

Prerequisites:

• Node.js (14.x or newer) and npm installed
• Access to Bitrefill API credentials if you plan to use create_invoice and related features

Install dependencies and build:

npm install
npm run build

Run the server locally (example):

npm start

Alternatively, run via npx (as configured in MCP client):

npx -y bitrefill-mcp-server

Environment variables (for full functionality):

BITREFILL_API_ID=your_api_id_here
BITREFILL_API_SECRET=your_api_key_here

Documentation and config are also compatible with Claude Desktop, Cline, Cursor, and Docker-based setups as described in the README.

Tips and notes:

• The create_invoice tool is only registered if BITREFILL_API_ID and BITREFILL_API_SECRET are set. If credentials are missing, that tool won’t appear in the available tools list.
• For debugging MCP communications, consider using the MCP Inspector tool and the provided npm script (npm run inspector) to obtain a debugging URL.
• When integrating with Claude Desktop or other clients, you can configure the MCP server in their respective config JSON by providing the command, args, and env blocks shown in the README.
• Docker users can run the server with appropriate environment variables; mounting the source during development is supported for hot-reloads if you’re using a volume.
• Ensure the API credentials are kept secret and never committed to public repositories.