Bitrefill Search and Shop

Bitrefill MCP 服务器

基于 TypeScript 的 MCP 服务器，提供对 Bitrefill 服务的访问，让您可以搜索礼品卡、手机充值等。该服务器实现了模型上下文协议 (MCP)，以便向 AI 助手公开 Bitrefill 功能。

工作原理

该服务器使用模型上下文协议 (MCP) 与 Claude 及类似的 AI 助手进行通信。它：

1. 作为独立进程运行，使用 stdio 进行通信
2. 注册用于访问 Bitrefill 服务的资源和工具
3. 与 Bitrefill API 接口以提供产品搜索和详细信息
4. 返回可由 AI 助手处理的结构化 JSON 响应

建筑学

应用服务器遵循以下架构：

特征

资源

• bitrefill://product-types - Bitrefill 上可用产品类型列表
• bitrefill://categories/{type} - 特定产品类型的可用类别列表（例如， bitrefill://categories/gift-cards ）

工具

• search - 搜索礼品卡、ESIM、手机充值等
  • 必填： 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 凭据：

1. 创建 Bitrefill 帐户
2. 通过此表单提交请求来获取开发人员 API 密钥
3. 在根目录中创建一个.env文件（您可以从.env.example复制）
4. 添加您的 Bitrefill API 凭证：
   BITREFILL_API_SECRET=your_api_key_here BITREFILL_API_ID=your_api_id_here

只有设置了 API 凭据后， create_invoice工具才可用。如果未设置 API 凭据，该工具将不会被注册，也不会出现在可用工具列表中。

发展

安装依赖项：

构建服务器：

对于使用自动重建的开发：

调试

由于 MCP 服务器通过 stdio 进行通信，调试起来可能比较困难。我们推荐使用MCP Inspector ，它以包脚本的形式提供：

检查器将提供一个 URL 来访问浏览器中的调试工具。

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Bitrefill：

克劳德桌面

添加服务器配置：

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

克莱恩

1. 打开 Cline 扩展设置
2. 打开“MCP 服务器”选项卡
3. 点击“配置 MCP 服务器”
4. 添加服务器配置：

其他 Cline 配置选项：

• disabled ：设置为false以启用服务器
• autoApprove ：每次使用时不需要明确批准的工具列表

光标

1. 打开光标设置
2. 打开“功能”设置
3. 在“MCP 服务器”部分，点击“添加新的 MCP 服务器”
4. 选择一个名称，并选择“命令”作为“类型”
5. 在“命令”字段中输入以下内容：

6. （可选）如果您使用create_invoice工具，请添加环境变量：
   • BITREFILL_API_SECRET: 你的 API 密钥在这里
   • BITREFILL_API_ID：此处为你的 API id

Docker

您也可以使用 Docker 运行服务器。首先，构建镜像：

然后运行容器：

对于开发，您可能希望将源代码作为卷挂载：