Bitrefill MCP Server

A TypeScript-based MCP server that provides access to Bitrefill services, allowing you to search for gift cards, mobile topups, and more. This server implements the Model Context Protocol to expose Bitrefill functionality to AI assistants.

How It Works

The server operates using the Model Context Protocol (MCP) to communicate with Claude and similar AI assistants. It:

Runs as a standalone process using stdio for communication
Registers resources and tools for accessing Bitrefill services
Interfaces with the Bitrefill API to provide product search and details
Returns structured JSON responses that can be processed by AI assistants

Architecture

The app server follows this architecture:

src/
├── index.ts                # Main entry point
├── constants/              # Static data
│   └── categories.ts       # Product categories
├── handlers/               # MCP request handlers
│   ├── resources.ts        # Resource endpoints
│   └── tools.ts            # Tool implementations
├── services/               # API services
│   ├── products.ts         # Product details service
│   └── search.ts           # Search functionality
├── types/                  # TypeScript definitions
│   └── index.ts            # Types for API responses
└── utils/                  # Utility functions
    └── index.ts            # Error logging, etc.

Features

Resources

bitrefill://product-types - List of available product types on Bitrefill
bitrefill://categories/{type} - List of available categories for a specific product type (e.g., bitrefill://categories/gift-cards)

Tools

search - Search for gift cards, esims, mobile topups and more
- Required: query (e.g., 'Amazon', 'Netflix', 'AT&T' or '*' for all)
- Optional: country, language, limit, skip, category
detail - Get detailed information about a product
- Required: id (product identifier)
categories - Get the full product type/categories map
- No required parameters

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Installation

Installing via Smithery

To install Bitrefill for Claude Desktop automatically via Smithery:

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

Claude Desktop

Add the server config 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"]
    }
  }
}

Cline

Open the Cline extension settings
Open "MCP Servers" tab
Click on "Configure MCP Servers"
Add the server config:

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

Additional Cline configuration options:

disabled: Set to false to enable the server
autoApprove: List of tools that don't require explicit approval for each use

Cursor

Open the Cursor settings
Open "Features" settings
In the "MCP Servers" section, click on "Add new MCP Server"
Choose a name, and select "command" as "Type"
In the "Command" field, enter the following:

npx -y bitrefill-mcp-server

Docker

You can also run the server using Docker. First, build the image:

docker build -t bitrefill-mcp-server .

Then run the container:

docker run -e bitrefill-mcp-server

For development, you might want to mount your source code as a volume:

docker run -v $(pwd):/app --env-file .env bitrefill-mcp-server

Bitrefill Search and Shop

Integrations