Africa's Talking Airtime MCP

该项目实现了使用 Africa's Talking API 管理话费交易的 Model Context Protocol (MCP) 服务器。它提供了一组工具来检查账户余额、发送话费、查看最近的充值交易、汇总最近的充值金额以及统计特定电话号码的充值次数。该应用程序使用 SQLite 存储交易数据，并支持非洲国家，这些国家由 Africa's Talking 话费服务支持，并具有正确的电话号码格式。

描述

Africa's Talking 话费 MCP 服务器 集成了 Africa's Talking 话费 API 以促进话费转账。主要功能包括：

• 向指定电话号码发送话费。
• 在 SQLite 数据库中存储交易详情。
• 检索和汇总交易历史记录。
• 检查 Africa's Talking 账户余额。

该应用程序支持 Africa's Talking 话费服务所支持的国家。

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 Africa's Talking 话费服务器，请运行以下命令：

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

前提条件

1. Python 3.10 或更高版本

2. 安装 uv

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

按照以下步骤在本地设置并运行项目：

1. 克隆仓库：
   bash
   git clone https://github.com/nasoma/africastalking-airtime-mcp.git
   cd africastalking-airtime-mcp

2. 设置虚拟环境并安装依赖项：
   bash
   uv sync

3. 一切就绪！

使用 AI 工具

与 Claude Desktop 一起使用

将以下内容添加到您的 claude_desktop_config.json 文件中：
json
{
"mcpServers": {
"Airtime Server": {
"command": "{{PATH_TO_UV}}", // 运行 which uv 并将输出放在这里
"args": [
"--directory",
"{{PATH_TO_PROJECT}}", // 进入仓库目录，运行 pwd 并输入输出
"run",
"main.py"
],
"env": {
"username": "your_africastalking_username",
"api_key": "your_africastalking_api_key",
"country":"your_country", # 例如 kenya, uganda, dr congo, rwanda, south africa
"currency_code":"currency-code" # 例如 KES, UGX, NGN
}
}
}
}

与 Goose 一起使用

如果您想使用您喜欢的 LLM 并提供 API 密钥，Goose 是一个不错的选择。

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

工具描述

MCP 提供了以下工具来管理话费交易：

1. check_balance:

   • 描述: 检索您的 Africa's Talking 账户当前的话费余额。
   • 用法: check_balance()
   • 输出: 返回账户余额（例如，“账户余额: KES 1234.00”），如果无法获取余额则返回错误消息。

2. load_airtime:

   • 描述: 向指定电话号码发送话费并将交易保存到数据库中。
   • 参数:
     • phone_number: 收件人的电话号码（例如，“0712345678”或“+254712345678”）。
     • amount: 要发送的话费金额（例如，100）。
     • currency_code: 货币代码（例如，“KES”）。- 用法: load_airtime("0712345678", 100.00, "KES")
   • 输出: 确认成功（例如，“已成功向+254712345678发送了KES 100.00的通话时间”）或报告错误。

3. get_last_topups:

   • 描述: 从数据库中检索最后N条充值交易记录。
   • 参数:
     • limit: 要检索的交易数量（默认值：3）。
   • 用法: get_last_topups(3)
   • 输出: 列出最近的交易（例如，“最后3笔充值交易：...”）或指示未找到交易。

4. sum_last_n_topups:

   • 描述: 计算最后N次成功充值的总金额，并确保它们使用相同的货币。
   • 参数:
     • n: 要求和的交易数量（默认值：3）。
   • 用法: sum_last_n_topups(3)
   • 输出: 返回总金额（例如，“最后3次成功充值的总金额：KES 300.00”）或如果货币不同则返回错误。

5. count_topups_by_number:

   • 描述: 统计特定电话号码的成功充值次数。
   • 参数:
     • phone_number: 要查询的电话号码（例如，“0712345678”）。
   • 用法: count_topups_by_number("0712345678")
   • 输出: 返回计数（例如，“向+254712345678成功充值的次数：5”）或错误信息。

示例提示

以下是用户可以询问AI以与Africa's Talking Airtime MCP交互的一些示例问题或命令，基于可用工具：

检查账户余额

• 我的Africa's Talking账户余额是多少？
• 你能显示一下当前余额吗？
• 检查我的通话时间余额。

发送通话时间

• 向0712345678发送100 KES的通话时间。
• 为0712345678充值60。
• 向+2348012345678加载50 NGN。
• 你能为0755123456充值200 UGX吗？

查看最近的充值

• 显示我最后3笔通话时间交易。
• 我最近的充值是什么？
• 列出最后5笔通话时间充值。

总结最近的充值

• 我最后3次充值的总额是多少？
• 将我最后4笔通话时间交易的金额相加。
• 我在最后5次充值中总共发送了多少？

按电话号码统计充值次数

• 我给0712345678充过几次值？
• 统计+254712345678的充值次数。
• 告诉我向0755123456成功充值了多少次。

注意事项

• 确保您的Africa's Talking账户有足够的资金来发送通话时间。
• 根据客户端中设置的country变量或claude_desktop_config.json中的设置自动格式化电话号码。
• 在初始化时，在项目目录中创建SQLite数据库（airtime_transactions.db）。
• 最适用于支持工具调用的模型，例如Claude 3.7 Sonnet。如果您对价格敏感，GPT-4.1 Nano是一个更便宜的选择，特别是在与Goose等客户端一起使用时。

🙏 致谢

• Africa's Talking API Africa's Talking文档。