Africa's Talking Airtime MCP

Africa's Talking Airtime MCP

此项目实现了一个 Model Context Protocol（MCP）服务，支持与 Africa's Talking API 无缝交互，执行话费相关操作。它提供一系列工具，用于查询账户余额、充值话费、查看交易历史记录以及汇总充值数据。该服务使用 SQLite 数据库进行持久化存储，并包含适用于多个非洲国家的电话号码格式处理逻辑。

主要功能

• 查询余额：即时获取 Africa's Talking 账户当前的话费余额。
• 充值话费：为支持的国家/地区中的任意电话号码充值。
• 交易记录：自动将每笔交易保存到本地 SQLite 数据库。
• 交易历史记录：查看最近的充值交易列表。
• 汇总充值金额：计算最近“n”笔充值的总金额。
• 统计充值次数：统计指定电话号码的交易次数。
• 电话号码格式处理：自动为电话号码添加正确的国家代码。

安装指南

前提条件

1. Python 3.10 或更高版本：请确保已安装较新版本的 Python。
2. uv 包管理器：此项目使用 uv 管理依赖项。运行以下命令进行安装：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Africa's Talking Airtime 服务：

npx -y @smithery/cli install @nasoma/africastalking-airtime-mcp --client claude

本地设置

1. 克隆仓库：

   git clone https://github.com/nasoma/africastalking-airtime-mcp.git
   cd africastalking-airtime-mcp
   

2. 安装依赖项： 使用 uv 创建虚拟环境并安装所需的软件包：

   uv sync
   

与 AI 工具搭配使用

与 Claude Desktop 搭配使用

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "Airtime Server": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}", // cd into the repo, run `pwd` and enter the output here
        "run",
        "main.py"
      ],
      "env": {
        "username": "your_africastalking_username",
        "api_key": "your_africastalking_api_key",
        "country":"your_country", # e.g kenya, uganda, dr congo, rwanda, south africa
        "currency_code":"currency-code"  # e.g. KES, UGX, NGN
      }
    }
  }
}

与 Goose 搭配使用

如果你想使用自己偏好的 LLM 并提供 API 密钥，Goose 是不错的选择。

• 安装 Goose。
• 打开设置面板并添加自定义扩展（MCP 服务）。
• 为扩展命名。类型选择 STDIO。
• 添加命令并保存更改。
• 添加环境变量：username、api_key、currency_code 和 country。
• 保存更改。

工具参考

此 MCP 服务提供以下话费管理工具：

check_balance

• 描述：从你的 Africa's Talking 账户获取当前的话费余额。
• 用法：check_balance()
• 返回值：显示账户余额的字符串（例如，“Account Balance: KES 1234.00”）或错误消息。

load_airtime

• 描述：向指定电话号码充值指定金额，并记录该笔交易。
• 参数：
  • phone_number（str）：接收方的电话号码。
  • amount（float）：要充值的话费金额。
  • currency_code（str）：货币代码（例如，“KES”“UGX”）。
• 用法：load_airtime(phone_number="0712345678", amount=100.0, currency_code="KES")
• 返回值：成功时返回确认消息，否则返回错误消息。

get_last_topups

• 描述：从数据库中获取最近 N 笔话费充值交易。
• 参数：
  • limit（int，可选）：要获取的交易数量。默认为 3。
• 用法：get_last_topups(limit=5)
• 返回：列出近期交易的格式化字符串。

sum_last_n_topups

• 描述：计算最近 N 笔充值的总额。
• 参数：
  • n（int，可选）：要计算总额的交易数量。默认为 3。
• 用法：sum_last_n_topups(n=5)
• 返回：包含总额的字符串；如果交易使用不同货币，则返回错误。

count_topups_by_number

• 描述：统计向指定电话号码成功充值的次数。
• 参数：
  • phone_number（str）：要查询的电话号码。
• 用法：count_topups_by_number(phone_number="0712345678")
• 返回：向指定号码充值的总次数。

示例提示词

以下是一些可用于与 MCP 服务交互的示例提示词：

• 查询余额：

  • “我的 Africa's Talking 账户余额是多少？”
  • “查询我的话费余额。”

• 发送话费：

  • “给 0712345678 充值 100 KES 话费。”
  • “给我的手机号 +254712345678 充值 50 bob。”
  • “给 0755123456 充值 200 UGX。”

• 查看最近的充值：

  • “显示最近 3 笔话费充值交易。”
  • “列出最近 5 笔充值。”

• 计算最近充值总额：

  • “最近 3 笔充值的总额是多少？”
  • “最近 5 笔交易一共花了多少钱？”

• 统计充值次数：

  • “我给 0712345678 充值过多少次？”
  • “统计向 +254712345678 充值的次数。”

重要说明

• 账户资金：确保 Africa's Talking 账户有足够的资金来发送话费。
• 电话号码格式：系统会根据 country 环境变量自动格式化电话号码。
• 数据库：SQLite 数据库（airtime_transactions.db）会自动在项目目录中创建。
• 支持的模型：此 MCP 服务最适合与支持工具调用的模型搭配使用，例如 Claude 3.7 Sonnet 或 GPT-4.1 Nano。

致谢

• Africa's Talking API：提供底层话费服务。请参阅官方文档。