check_balanceLABSCO SUMMARY
The local ledger is what makes it more than an API call.
Sending airtime is one API call; knowing what you have already sent is the part providers make you dig for. Writing each transaction to SQLite means the history, the running totals and the per-number counts are answerable in the same conversation as the send. Two things to hold in mind: this moves real balance, and summing across mixed currencies returns an error rather than a plausible-looking wrong figure — which is the right behaviour, but you will meet it.
What it is
An MCP server over the Africa's Talking airtime API. It sends airtime, checks what is left on the account, and writes every transaction to a local SQLite database so the history questions — what did I send, to whom, how much in total — can be answered without going back to the provider.
What you get
- The current airtime balance on your Africa's Talking account, or the error if the call failed —
check_balance - Airtime sent to a phone number for a given amount and currency code, with the transaction recorded —
load_airtime - The most recent top-up transactions, defaulting to the last 3 —
get_last_topups - The sum of the last N top-ups, defaulting to 3, with an error rather than a wrong number if the transactions are in different currencies —
sum_last_n_topups - How many successful top-ups have gone to one phone number —
count_topups_by_number - Phone numbers formatted to the right country code automatically, from the country you configured
Requirements
An Africa's Talking account with funds on it — sending airtime spends real money. Four environment values go in the client entry: username, api_key, country (kenya, uganda, dr congo, rwanda, south africa) and currency_code (KES, UGX, NGN). Python 3.10 or higher and the uv package manager; uv sync sets up the environment, and the client runs uv with --directory pointing at the repository and main.py as the target. The database file airtime_transactions.db is created in the project directory on first use. The pyproject name is africas-talking-airtime-mcp-server (0.1.0).
Setup effort
Build from source
USE CASES
01
Topping someone up without opening a dashboard
Give a number, an amount and a currency; the number gets formatted to the right country code and the send is recorded.
02
Knowing what you have spent recently
List the last few top-ups and total them, to see where the account balance went.
03
Checking whether a number has already been paid
Count successful top-ups to a specific phone number before sending another one.
04
Making sure there is enough to send
Read the account balance first, so a batch of sends does not fail halfway through.
5 tools
Listed in project docs. Your client may show a different list.
load_airtimeget_last_topupssum_last_n_topupscount_topups_by_numberBEFORE YOU INSTALL
What to know first
Tools you get
5 tools named in the project's documentation.
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
MCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"Airtime Server": {
"command": "<YOUR_PATH_TO_UV>",
"args": [
"--directory",
"<YOUR_PATH_TO_PROJECT>",
"run",
"main.py"
],
"env": {
"username": "<YOUR_USERNAME>",
"api_key": "<YOUR_API_KEY>",
"country": "<YOUR_COUNTRY>",
"currency_code": "<YOUR_CURRENCY_CODE>"
}
}
}
}
