Africa's Talking Airtime MCP server

Africa's Talking Airtime MCP is a server implementation that allows you to manage airtime transactions using Africa's Talking API. It provides tools to check account balance, send airtime to phone numbers, view transaction history, and analyze top-up patterns, all while storing transaction data in SQLite for future reference.

Installation Options

Installing via Smithery

For automatic installation with Claude Desktop:

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

Manual Installation

Prerequisites

1. Python 3.10 or higher
2. The uv package manager:

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

Installation Steps

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:

uv sync

Configuring with AI Tools

Claude Desktop Setup

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "Airtime Server": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}",
        "run",
        "main.py"
      ],
      "env": {
        "username": "your_africastalking_username",
        "api_key": "your_africastalking_api_key",
        "country":"your_country",
        "currency_code":"currency-code"
      }
    }
  }
}

Replace the placeholders:

• {{PATH_TO_UV}}: Output of which uv command
• {{PATH_TO_PROJECT}}: Full path to project directory
• your_country: e.g., kenya, uganda, dr congo, rwanda, south africa
• currency_code: e.g., KES, UGX, NGN

Goose Setup

If you prefer using Goose:

1. Install Goose
2. Open settings panel and add a custom extension (MCP Server)
3. Name your extension and set type to STDIO
4. Add the command and save changes
5. Add environment variables: username, api_key, currency_code and country
6. Save changes

Available Tools

Check Balance

Retrieves your current Africa's Talking account balance.

check_balance()

Example response: "Account Balance: KES 1234.00"

Send Airtime

Sends airtime to a specified phone number and saves the transaction.

load_airtime("0712345678", 100.00, "KES")

Parameters:

• phone_number: Recipient's phone number
• amount: Amount of airtime to send
• currency_code: Currency code (e.g., "KES")

Example response: "Successfully sent KES 100.00 airtime to +254712345678"

View Recent Transactions

Retrieves the most recent airtime top-up transactions.

get_last_topups(3)

Parameters:

• limit: Number of transactions to retrieve (default: 3)

Calculate Total of Recent Top-ups

Calculates the total amount of recent successful top-ups.

sum_last_n_topups(3)

Parameters:

• n: Number of transactions to sum (default: 3)

Example response: "Sum of last 3 successful top-ups: KES 300.00"

Count Top-ups by Phone Number

Counts successful top-ups to a specific number.

count_topups_by_number("0712345678")

Parameters:

• phone_number: The phone number to query

Example response: "Number of successful top-ups to +254712345678: 5"

Example Prompts

Check Account Balance

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

Send Airtime

• Send 100 KES airtime to 0712345678
• Topup my 0712345678 with 60
• Load 50 NGN to +2348012345678

View Recent Top-Ups

• Show me the last 3 airtime transactions
• What are my most recent 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

Count Top-Ups by Phone Number

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

Important Notes

• Your Africa's Talking account must be funded to send airtime
• Phone numbers are automatically formatted based on the country variable
• A SQLite database (airtime_transactions.db) is created to store transactions
• Works best with models that support tool calling like Claude 3.7 Sonnet or GPT-4.1 Nano

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.