Africa's Talking Airtime MCP

This project implements a Model Context Protocol (MCP) server that enables seamless interaction with the Africa's Talking API for airtime-related operations. It provides a suite of tools for checking account balances, sending airtime, viewing transaction history, and summarizing top-up data. The server uses an SQLite database for persistent storage and includes logic for formatting phone numbers for various African countries.

Key Features

• Check Balance: Instantly retrieve the current airtime balance of your Africa's Talking account.
• Send Airtime: Load airtime to any phone number in supported countries.
• Transaction Logging: Automatically save every transaction to a local SQLite database.
• Transaction History: View a list of the most recent top-up transactions.
• Summarize Top-ups: Calculate the total amount of the last 'n' top-ups.
• Count Top-ups: Count the number of transactions for a specific phone number.
• Phone Number Formatting: Automatically formats phone numbers to include the correct country code.

Installation Guide

Prerequisites

1. Python 3.10 or higher: Ensure you have a modern version of Python installed.

2. `uv` Package Manager: This project uses `uv` for dependency management. Install it by running:

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

Installing from Smithery

To install Africa's Talking Airtime Server for Claude Desktop automatically via Smithery:

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

Local Setup

1. Clone the Repository:

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

2. Install Dependencies:

Set up the virtual environment and install the required packages using `uv`:

uv sync

Using with AI Tools

With Claude Desktop

Add this to your `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
      }
    }
  }
}

With Goose

Goose is a good option if you want to use your preferred LLM and supply an API key.

• Install Goose.
• Open the settings panel and add a custom extension (MCP Server).
• Give your extension a name. Type is STDIO.
• Add the command. Save changes.

• Add your environment variables: `username`, `api_key`, `currency_code` and `country`.
• Save changes.

Tool Reference

The MCP server exposes the following tools for managing airtime:

`check_balance`

• Description: Retrieves the current airtime balance from your Africa's Talking account.
• Usage: `check_balance()`
• Returns: A string displaying the account balance (e.g., "Account Balance: KES 1234.00") or an error message.

`load_airtime`

• Description: Sends a specified amount of airtime to a phone number and records the transaction.
• Arguments:
  • `phone_number` (str): The recipient's phone number.
  • `amount` (float): The amount of airtime to send.
  • `currency_code` (str): The currency code (e.g., "KES", "UGX").
• Usage: `load_airtime(phone_number="0712345678", amount=100.0, currency_code="KES")`
• Returns: A confirmation message upon success or an error message.

`get_last_topups`

• Description: Fetches the last `N` airtime top-up transactions from the database.
• Arguments:
  • `limit` (int, optional): The number of transactions to retrieve. Defaults to 3.
• Usage: `get_last_topups(limit=5)`
• Returns: A formatted string listing the recent transactions.

`sum_last_n_topups`

• Description: Calculates the sum of the last `N` top-ups.
• Arguments:
  • `n` (int, optional): The number of transactions to sum. Defaults to 3.
• Usage: `sum_last_n_topups(n=5)`
• Returns: A string with the total sum, or an error if transactions have different currencies.

`count_topups_by_number`

• Description: Counts the number of successful top-ups to a specific phone number.
• Arguments:
  • `phone_number` (str): The phone number to query.
• Usage: `count_topups_by_number(phone_number="0712345678")`
• Returns: The total count of top-ups for the given number.

Example Prompts

Here are some example prompts you can use to interact with the MCP server:

• Check Balance:
  • "What is my Africa's Talking account balance?"
  • "Check my airtime balance."

• Send Airtime:
  • "Send 100 KES airtime to 0712345678."
  • "Top up my phone +254712345678 with 50 bob."
  • "Load 200 UGX to 0755123456."

• View Recent Top-ups:
  • "Show me the last 3 airtime transactions."
  • "List my 5 most recent top-ups."

• Sum Recent Top-ups:
  • "What is the total of my last 3 top-ups?"
  • "How much have I spent in my last 5 transactions?"

• Count Top-ups:
  • "How many times have I topped up 0712345678?"
  • "Count the top-ups to +254712345678."

Important Notes

• Funding: Ensure your Africa's Talking account has sufficient funds to send airtime.
• Phone Number Formatting: Phone numbers are automatically formatted based on the `country` environment variable.
• Database: The SQLite database (`airtime_transactions.db`) is automatically created in the project directory.
• Supported Models: This MCP server works best with models that support tool calling, such as `Claude 3.7 Sonnet` or `GPT-4.1 Nano`.

Credits

• Africa's Talking API: For the underlying airtime service. See the official documentation.