Bitrefill MCP Server

🚀 BitRefill MCP Server

The BitRefill MCP Server is a TypeScript-based Minimum Viable Product (MCP) server that provides BitRefill services through the Model Context Protocol.

🚀 Quick Start

The BitRefill MCP Server is a TypeScript-based Minimum Viable Product (MCP) server designed to offer BitRefill services via the Model Context Protocol. It enables AI assistants, such as Claude, to access BitRefill's features, including searching for gift cards and e-money, mobile top-ups, and other related services.

✨ Features

• Search Function: Allows users to search for gift cards and e-money.
• Mobile Top-up: Enables users to top up their mobile phones.
• Other Related Services: Provides additional relevant services.

📦 Installation

Install via npm

1. Clone the repository:

   git clone https://github.com/bitrefill/bitrefill-mcp-server.git
   cd bitrefill-mcp-server
   

2. Install dependencies:

   npm install
   

Install via Smithery

To automatically install BitRefill through Smithery:

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

💻 Usage Examples

Configuration

Create a .env file in the root directory (refer to .env.example) and add the following content:

BITREFILL_API_SECRET=your_api_key_here
BITREFILL_API_ID=your_api_id_here

Available Tools

• search: Search for available gift cards and e-money.
• invoice: Create an invoice request (API credentials required).

Note: If API credentials are not set, the create_invoice tool will not be available and will not be registered with the MCP server.

Development

Build

npm run build

Monitor Development

npm run watch

Debugging

Since the BitRefill MCP Server communicates via standard input/output (stdio), you can use any MCP-supported tool for debugging. We recommend using MCP Inspector:

npm run inspector

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

Usage in Different Environments

Usage in Claude Desktop

Add the server configuration to the following path:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

The configuration content is as follows:

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["@smithery/cli", "start"],
      "env": {
        "BITREFILL_API_SECRET": "your_api_key_here",
        "BITREFILL_API_ID": "your_api_id_here"
      }
    }
  }
}

Usage in Cline

Add the following content to the ~/.config/eline/mcp-config.json file:

{
  "servers": {
    "bitrefill": {
      "command": "npx",
      "args": ["@smithery/cli", "start"],
      "env": {
        "BITREFILL_API_SECRET": "your_api_key_here",
        "BITREFILL_API_ID": "your_api_id_here"
      }
    }
  }
}

Usage in Cursor

Add the following content to the config/cursor.mcp.json file:

{
  "servers": {
    "bitrefill": {
      "command": "npx",
      "args": ["@smithery/cli", "start"],
      "env": {
        "BITREFILL_API_SECRET": "your_api_key_here",
        "BITREFILL_API_ID": "your_api_id_here"
      }
    }
  }
}

Using Docker

docker build -t bitrefill-mcp-server .
docker run -it --rm -e BITREFILL_API_SECRET=your_api_key_here -e BITREFILL_API_ID=your_api_id_here bitrefill-mcp-server

📚 Documentation

How it Works

The BitRefill MCP Server provides tools through the Model Context Protocol (MCP), enabling AI assistants (such as Claude) to call BitRefill's functions. Here's the server's workflow:

1. Tool Registration: When the server starts, it registers available tools with the MCP.
2. Request Handling: When a tool request is received, the server performs the corresponding operation.
3. Response Return: The server returns the result in a structured format (JSON).
4. Error Handling: If an error occurs, the server returns a JSON response containing error information.

MCP Communication

Since the BitRefill MCP Server communicates via standard input/output (stdio), any MCP-supported tool can be used for debugging.

🔧 Technical Details

Directory Structure

bitrefill-mcp-server/
├── src/             # Source code
│   ├── server.ts    # Main server file
│   └── tools/       # Available tools
└── package.json     # Project dependencies and configuration