Africa's Talking Airtime MCP

This project implements a Model Context Protocol (MCP) server for managing airtime transactions using the Africa's Talking API. It provides a set of tools to check account balance, send airtime, view recent top-up transactions, sum the amounts of recent top-ups, and count top-ups for a specific phone number. The application uses SQLite to store transaction data and supports African countries supported by Africa's Talking Airtime Service with proper phone number formatting.

<a href="https://glama.ai/mcp/servers/@nasoma/africastalking-airtime-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@nasoma/africastalking-airtime-mcp/badge" /> </a>

Description

The Africa's Talking Airtime MCP Server integrates with the Africa's Talking Airtime API to facilitate airtime transfers. Key features include:

• Sending airtime to specified phone numbers.
• Storing transaction details in a SQLite database.
• Retrieving and summarizing transaction history.
• Checking the account balance on Africa's Talking.

The application supports the countries where Africa's Talking Airtime service is supported.

Installation

Prerequisites

1. Python 3.10 or higher

2. Install uv

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

Follow these steps to set up and run the project locally:

1. Clone the repository:

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

2. Set up the virtual environment and install dependencies by running:

uv sync 

3. You are good to go!

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 Goosee.
• 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 chnages.

Tools Descriptions

The MCP provides the following tools for managing airtime transactions:

1. check_balance:

   • Description: Retrieves the current airtime balance for your Africa's Talking account.
   • Usage: check_balance()
   • Output: Returns the account balance (e.g., "Account Balance: KES 1234.00") or an error message if the balance cannot be fetched.

2. load_airtime:

   • Description: Sends airtime to a specified phone number and saves the transaction in the database.
   • Parameters:
     • phone_number: The recipient's phone number (e.g., "0712345678" or "+254712345678").
     • amount: The amount of airtime to send (e.g., 100).
     • currency_code: The currency code (e.g., "KES").
   • Usage: load_airtime("0712345678", 100.00, "KES")
   • Output: Confirms success (e.g., "Successfully sent KES 100.00 airtime to +254712345678") or reports an error.

3. get_last_topups:

   • Description: Retrieves the last N airtime top-up transactions from the database.
   • Parameters:
     • limit: Number of transactions to retrieve (default: 3).
   • Usage: get_last_topups(3)
   • Output: Lists recent transactions (e.g., "Last 3 top-up transactions: ...") or indicates no transactions found.

4. sum_last_n_topups:

   • Description: Calculates the total amount of the last N successful top-ups, ensuring they use the same currency.
   • Parameters:
     • n: Number of transactions to sum (default: 3).
   • Usage: sum_last_n_topups(3)
   • Output: Returns the sum (e.g., "Sum of last 3 successful top-ups: KES 300.00") or an error if currencies differ.

5. count_topups_by_number:

   • Description: Counts the number of successful top-ups to a specific phone number.
   • Parameters:
     • phone_number: The phone number to query (e.g., "0712345678").
   • Usage: count_topups_by_number("0712345678")
   • Output: Returns the count (e.g., "Number of successful top-ups to +254712345678: 5") or an error.

Example prompts

The following are example questions or commands users can ask the AI to interact with the Africa's Talking Airtime MCP, based on the available tools:

Check Account Balance

• What is my Africa's Talking account balance?
• Can you show me the current balance?
• Check my airtime balance.

Send Airtime

• Send 100 KES airtime to 0712345678.
• Topup my 0712345678 with 60.
• Load 50 NGN to +2348012345678.
• Can you top up 200 UGX to 0755123456?

View Recent Top-Ups

• Show me the last 3 airtime transactions.
• What are my most recent top-ups?
• List the last 5 airtime top-ups.

Sum Recent Top-Ups

• What is the total of my last 3 top-ups?
• Sum the amounts of my last 4 airtime transactions.
• How much have I sent in my last 5 top-ups?

Count Top-Ups by Phone Number

• How many times have I topped up 0712345678?
• Count the top-ups to +254712345678.
• Tell me how many successful top-ups were made to 0755123456.

Notes

• Ensure your Africa's Talking account is funded to send airtime.
• Phone numbers are automatically formatted based on the country variable set in the client or on claude_desktop_config.json.
• The SQLite database (airtime_transactions.db) is created in the project directory upon initialization.
• Works best with models that support tool calling, e.g Claude 3.7 Sonnet. If you are price conscious GPT-4.1 Nano is a good, cheaper option when used with clients like Goose.

🙏 Credits

• Africa's Talking API Africa's Talking Documentation.