比特充值-MCP服务器
项目介绍
Bitrefill MCP 服务器
这是一个基于 TypeScript 的 MCP 服务器，提供对接 Bitrefill 服务的访问，允许您搜索礼品卡、手机充值等。此服务器实现了模型上下文协议（Model Context Protocol），以将 Bitrefill 功能暴露给 AI 助手。
工作原理
该服务器使用模型上下文协议（MCP）与 Claude 和类似的 AI 助手进行通信。它：
- 使用标准 I/O 作为独立进程运行进行通信
- 注册资源和工具以访问 Bitrefill 服务
- 通过 Bitrefill API 提供产品搜索和详细信息
- 返回结构化的 JSON 响应，这些响应可以由 AI 助手处理
架构
应用服务器遵循以下架构：
src/
├── index.ts # 主入口点
├── constants/ # 静态数据
│ ├── categories.ts # 产品类别
│ └── payment_methods.ts # 支付方式
├── handlers/ # MCP 请求处理器
│ ├── resources.ts # 资源端点
│ └── tools.ts # 工具实现
├── schemas/ # 数据验证模式
│ ├── detail.ts # 产品详情响应类型
│ ├── invoice.ts # 发票模式
│ ├── misc.ts # 杂项模式
│ ├── order.ts # 订单模式
│ └── search.ts # 搜索参数和响应类型
├── services/ # API 服务
│ ├── invoices.ts # 发票服务
│ ├── misc.ts # 杂项服务
│ ├── orders.ts # 订单服务
│ ├── products.ts # 产品详情服务
│ └── search.ts # 搜索功能
└── utils/ # 实用函数
├── index.ts # 错误日志等
└── api/ # API 客户端
├── authenticated.ts # 认证的 API 客户端
├── base.ts # 基础 API 客户端
└── public.ts # 公共 API 客户端
特性
资源
bitrefill://product-types- Bitrefill 上可用的产品类型列表bitrefill://categories/{type}- 特定产品类型可用的类别列表（例如，bitref fill://categories/gift-cards）
工具
-
search- 搜索礼品卡、esims、手机充值等- 必需：
query（例如，'Amazon'，'Netflix'，'AT&T' 或 '*' 表示所有） - 可选：
country，language，limit，skip，category
- 必需：
-
detail- 获取产品的详细信息- 必需：
id（产品标识符）
- 必需：
-
categories- 获取完整的产品类型/类别映射- 不需要任何参数
-
create_invoice- 创建购买产品的新发票（需要 API 密钥）- 必需：
products（要包含在发票中的产品数组）- 每个产品都需要：
product_id - 可选的产品字段：
quantity，value，package_id，phone_number，email，send_email，send_sms
- 每个产品都需要：
- 必需：
payment_method（其中之一："balance"，"bitcoin"，"lightning"） - 可选：
webhook_url，auto_pay
- 必需：
-
get_invoices- 检索带有可选过滤器的发票列表- 可选：
start，limit，after，before
- 可选：
-
get_invoice- 根据 ID 检索特定发票的详细信息- 必需：
id（发票标识符）
- 必需：
-
pay_invoice- 支付未支付的发票（仅适用于“余额”支付方式）- 必需：
id（发票标识符）
- 必需：
-
get_orders- 检索带有可选过滤器的订单列表- 可选：
start，limit，after，before
- 可选：
-
get_order- 根据 ID 检索特定订单的详细信息- 必需：
id（订单标识符）
- 必需：
-
unseal_order- 根据 ID 揭示特定订单的代码和 PIN- 必需：
id（订单标识符）
- 必需：
-
get_account_balance- 检索您的账户余额- 不需要任何参数
-
ping- 检查 Bitrefill API 是否可用- 不需要任何参数
配置
API 密钥设置
要使用除 search、categories 和 detail 之外的所有依赖于 Bitrefill API 的工具，您需要设置 Bitrefill API 凭据：
- 创建一个 Bitrefill 账户
- 通过填写 此表单 请求开发者 API 密钥
- 在根目录中创建一个
.env文件（您可以从.env.example复制） - 添加您的 Bitrefill API 凭据：
BITREFILL_API_SECRET=your_api_key_here BITREFILL_API_ID=your_api_id_here
只有设置了 API 凭据时，create_invoice 工具才会可用。如果未设置 API 凭据，则不会注册该工具，也不会出现在可用工具列表中。
开发
安装依赖项：
npm install
构建服务器：
npm run build
开发时自动重建：
npm run watch
调试
由于 MCP 服务器通过标准 I/O 进行通信，调试可能会很困难。我们推荐使用 MCP Inspector，它作为一个包脚本提供：
npm run inspector
Inspector 将提供一个 URL，以便您可以在浏览器中访问调试工具。
安装
通过 Smithery 安装
要通过 Smithery 自动安装 Bitrefill for Claude Desktop：
npx -y @smithery/cli install @bitrefill/bitrefill-mcp-server --client claude
Claude Desktop
在以下位置添加服务器配置：
- 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
- 打开 Cline 扩展设置
- 打开“MCP 服务器”标签
- 点击“配置 MCP 服务器”
- 添加服务器配置：
{
"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"
}
}
}
}
额外的 Cline 配置选项：
disabled：设置为false启用服务器autoApprove：不需要每次使用都明确批准的工具列表
Cursor
- 打开 Cursor 设置
- 打开“功能”设置
- 在“MCP 服务器”部分，点击“添加新的 MCP 服务器”
- 选择一个名称，并选择“命令”作为类型
- 在“命令”字段中输入以下内容：
npx -y bitrefill-mcp-server
- （可选）如果您使用
create_invoice工具，请添加环境变量：- BITREFILL_API_SECRET: your_api_key_here
- BITREFILL_API_ID: your_api_id_here
Docker
您还可以使用 Docker 运行服务器。首先，构建镜像：
docker build -t bitrefill-mcp-server .
然后运行容器：
docker run -e BITREFILL_API_SECRET=your_api_key_here -e BITREFILL_API_ID=your_api_id_here bitrefill-mcp-server
对于开发，您可能希望将源代码挂载为卷：
docker run -v $(pwd):/app --env-file .env bitrefill-mcp-server