이 프로젝트는 아프리카의 Talking API를 사용하여 통화량 거래를 관리하는 모델 컨텍스트 프로토콜(MCP) 서버를 구현합니다. 계좌 잔액 확인, 통화량 전송, 최근 충전 거래 내역 조회, 최근 충전 금액 합산, 그리고 특정 전화번호에 대한 충전 횟수 계산을 위한 도구 세트를 제공합니다. 이 애플리케이션은 SQLite를 사용하여 거래 데이터를 저장하고, 아프리카의 Talking Airtime Service가 지원하는 아프리카 국가들의 전화번호 형식을 지원합니다.
Africa's Talking Airtime MCP 서버는 Africa's Talking Airtime API와 통합되어 통화 시간 전송을 용이하게 합니다. 주요 기능은 다음과 같습니다.
지정된 전화번호로 통화 시간을 보냅니다.
SQLite 데이터베이스에 거래 세부 정보를 저장합니다.
거래 내역을 검색하고 요약합니다.
Africa's Talking에서 계좌 잔액을 확인합니다.
이 애플리케이션은 Africa's Talking Airtime 서비스가 지원되는 국가를 지원합니다.
Related MCP server: mpesa-mcp
Smithery를 통해 Claude Desktop에 Africa's Talking Airtime Server를 자동으로 설치하려면:
지엑스피1
Python 3.10 이상
curl -LsSf https://astral.sh/uv/install.sh | sh프로젝트를 로컬로 설정하고 실행하려면 다음 단계를 따르세요.
저장소를 복제합니다.
git clone https://github.com/nasoma/africastalking-airtime-mcp.git
cd africastalking-airtime-mcp다음을 실행하여 가상 환경을 설정하고 종속성을 설치합니다.
uv sync 이제 시작입니다!
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
}
}
}
}원하는 LLM을 사용하고 API 키를 제공하려는 경우 Goose 는 좋은 옵션입니다.
Goose를 설치하세요.
설정 패널을 열고 사용자 지정 확장 프로그램(MCP 서버)을 추가합니다.
확장 프로그램의 이름을 지정하세요. 유형은 STDIO입니다.
명령을 추가하고 변경 사항을 저장하세요.
환경 변수를 추가합니다: username , api_key , currency_code , country .
변경 사항을 저장합니다.
MCP는 통화 시간 거래를 관리하기 위한 다음과 같은 도구를 제공합니다.
체크_잔액 :
설명 : Africa's Talking 계정의 현재 통화 잔액을 검색합니다.
사용법 : check_balance()
출력 : 계좌 잔액(예: "계좌 잔액: KES 1234.00")을 반환하거나 잔액을 가져올 수 없는 경우 오류 메시지를 반환합니다.
로드_에어타임 :
설명 : 지정된 전화번호로 통화 시간을 보내고 데이터베이스에 거래를 저장합니다.
매개변수 :
phone_number : 수신자의 전화번호(예: "0712345678" 또는 "+254712345678").
amount : 보낼 통화 시간의 양(예: 100)
currency_code : 통화 코드(예: "KES")입니다.
사용법 : load_airtime("0712345678", 100.00, "KES")
출력 : 성공 확인(예: "+254712345678로 KES 100.00 통화 시간을 성공적으로 보냈습니다") 또는 오류를 보고합니다.
마지막_토핑_받기 :
설명 : 데이터베이스에서 마지막 N 통화료 충전 거래를 검색합니다.
매개변수 :
limit : 검색할 거래 수(기본값: 3).
사용법 : get_last_topups(3)
출력 : 최근 거래 내역을 나열합니다(예: "마지막 3개 충전 거래: ...") 또는 거래 내역이 없음을 나타냅니다.
마지막_n_충전_합계 :
설명 : 마지막으로 성공한 N 충전 총액을 계산하여 동일한 통화를 사용하는지 확인합니다.
매개변수 :
n : 합산할 거래 수(기본값: 3).
사용법 : sum_last_n_topups(3)
출력 : 합계(예: "마지막 3개 성공적인 충전 합계: KES 300.00")를 반환하거나 통화가 다르면 오류를 반환합니다.
개수별_충전_카운트 :
설명 : 특정 전화번호에 대한 성공적인 충전 횟수를 센다.
매개변수 :
phone_number : 쿼리할 전화번호(예: "0712345678").
사용법 : count_topups_by_number("0712345678")
출력 : 카운트(예: "성공적인 충전 횟수 +254712345678: 5") 또는 오류를 반환합니다.
다음은 사용 가능한 도구를 기반으로 사용자가 AI에게 Africa's Talking Airtime MCP와 상호 작용하도록 요청할 수 있는 질문이나 명령의 예입니다.
내 Africa's Talking 계좌 잔액은 얼마입니까?
현재 잔액을 보여 주실 수 있나요?
내 통화시간 잔액을 확인하세요.
0712345678로 100 KES 통화료를 보내세요.
제 0712345678에 60을 충전해 주세요.
50 NGN을 +2348012345678로 충전하세요.
0755123456에 200 UGX를 충전해 주실 수 있나요?
최근 3건의 통화 거래 내역을 보여주세요.
제가 가장 최근에 충전한 내역은 무엇인가요?
최근 5건의 통화시간 충전 내역을 나열하세요.
제가 최근 3번 충전한 금액은 얼마입니까?
최근 4번의 통화료 거래 금액을 합산하세요.
지난 5번의 충전에 얼마를 보냈나요?
0712345678에 몇 번 충전했나요?
충전 횟수를 +254712345678로 세어보세요.
0755123456으로 충전이 성공적으로 이루어진 횟수를 알려주세요.
Africa's Talking 계정에 통화 시간을 보낼 수 있는 금액이 있는지 확인하세요.
전화번호는 클라이언트나 claude_desktop_config.json 에 설정된 country 변수에 따라 자동으로 형식이 지정됩니다.
SQLite 데이터베이스( airtime_transactions.db )는 초기화 시 프로젝트 디렉토리에 생성됩니다.
Claude 3.7 Sonnet 처럼 도구 호출을 지원하는 모델에서 가장 잘 작동합니다. 가격에 민감하다면 Goose와 같은 클라이언트와 함께 사용할 경우 GPT-4.1 Nano 저렴하고 좋은 옵션입니다.
아프리카의 토킹 API 아프리카의 토킹 문서 .
Checks the airtime balance of the Africa's Talking account.
This tool connects to the Africa's Talking API to fetch the user's
current application data, which includes the account balance.
Returns:
str: A message displaying the account balance or an error if the
balance cannot be retrieved.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: connecting to an external API, fetching application data, and returning either a balance message or an error. It covers the core operation and error handling, though it lacks details like rate limits, authentication requirements, or specific error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose. The second sentence adds necessary detail about the API connection, and the 'Returns' section clarifies output behavior. It's efficient with minimal waste, though the 'Returns' formatting could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is reasonably complete. It explains what the tool does, how it operates via API, and what it returns. For a simple balance check tool, this covers essential context, though it could benefit from more detail on error scenarios or API specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of inputs. The description adds value by confirming no parameters are needed ('checks the airtime balance' implies a simple query without inputs), aligning with the schema. Baseline is 4 for 0 parameters, as it provides clear semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Checks') and resource ('airtime balance of the Africa's Talking account'), distinguishing it from sibling tools that focus on top-up operations rather than balance inquiry. It precisely defines what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning it fetches 'application data' and 'account balance', suggesting it's for checking current balance status. However, it doesn't explicitly state when to use this tool versus alternatives like checking transaction history through sibling tools, nor does it provide exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts the number of top-ups for a specific phone number.
Args:
phone_number (str): The phone number to count transactions for.
Returns:
str: The total count of top-ups for the given number or an error message.
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool counts top-ups and returns a count or error message, but lacks details on permissions, rate limits, error conditions, or data freshness. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by clear sections for arguments and returns. Every sentence earns its place by directly supporting tool understanding, with no redundant or verbose language, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and parameter semantics but lacks behavioral details like error handling or usage guidelines. For a simple query tool, it meets minimum viability but has clear gaps in contextual richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'phone_number' by explaining it is 'the phone number to count transactions for,' which clarifies its role beyond the schema's basic type and title. With schema description coverage at 0%, the description effectively compensates by providing semantic value, though it could include format examples (e.g., E.164).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Counts') and resource ('number of top-ups for a specific phone number'), distinguishing it from siblings like 'check_balance' (balance checking), 'get_last_topups' (retrieving recent transactions), 'load_airtime' (airtime loading), and 'sum_last_n_topups' (summing recent transactions). It precisely defines what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where counting top-ups is preferred over other tools like 'get_last_topups' or 'sum_last_n_topups', nor does it specify prerequisites or exclusions. Usage is implied only by the purpose statement, lacking explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the last N top-up transactions from the database.
Args:
limit (int, optional): The number of recent transactions to fetch.
Defaults to 3.
Returns:
str: A formatted string listing the last N transactions or a message
if no transactions are found.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool as retrieving transactions and returning a formatted string or message, which covers basic behavior. However, it lacks details on error handling, data format specifics, or performance aspects like rate limits or permissions needed, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with a clear purpose statement followed by structured sections for arguments and returns. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, parameter semantics, and return behavior. However, it could improve by addressing potential edge cases or linking to sibling tools for better context, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'limit,' explaining it as 'the number of recent transactions to fetch' with a default of 3, which goes beyond the input schema's basic type and title. Since schema description coverage is 0%, the description compensates well by providing clear semantics for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('retrieves') and resource ('last N top-up transactions from the database'). It distinguishes from siblings by focusing on recent transactions rather than checking balances, counting by number, loading airtime, or summing amounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'last N top-up transactions,' suggesting it's for recent transaction review rather than other operations like checking balances or loading airtime. However, it does not explicitly state when to use this tool versus alternatives like 'sum_last_n_topups' or 'count_topups_by_number,' missing explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends airtime to a specified phone number and logs the transaction.
This tool formats the phone number, sends the airtime using the
Africa's Talking API, and saves a record of the transaction in the
database.
Args:
phone_number (str): The recipient's phone number.
amount (float): The amount of airtime to send.
currency_code (str): The currency for the transaction (e.g., "KES").
Returns:
str: A message indicating the status of the airtime transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number | Yes | ||
| amount | Yes | ||
| currency_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: formatting phone numbers, using Africa's Talking API, and logging to a database. However, it lacks details on error handling, rate limits, authentication needs, or what specific data is logged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds necessary detail without redundancy. The Args/Returns sections are clearly formatted and efficiently convey parameter and return value information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description does a good job covering purpose, parameters, and basic behavior. However, it lacks details about the return message format, error conditions, or database logging specifics that would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantic meaning for all three parameters: phone_number identifies the recipient, amount specifies airtime quantity, and currency_code defines transaction currency with an example ('KES'). This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('sends airtime', 'logs the transaction') and identifies the resource (phone number). It distinguishes from sibling tools like check_balance or get_last_topups by focusing on sending rather than querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for sending airtime via Africa's Talking API, but provides no explicit guidance on when to use this tool versus alternatives like count_topups_by_number or sum_last_n_topups. No prerequisites, exclusions, or comparison to siblings are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculates the sum of the last 'n' successful top-ups.
This tool retrieves the last 'n' transactions from the database and
calculates their total sum. It ensures that all transactions are in the
same currency before summing.
Args:
n (int, optional): The number of recent top-ups to sum. Defaults to 3.
Returns:
str: The total sum of the last 'n' top-ups or an error message if
the currencies are mixed or no transactions are found.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses key behavioral traits: it only sums successful top-ups, retrieves from a database, ensures currency consistency, and handles error cases (mixed currencies or no transactions). It doesn't cover aspects like performance, rate limits, or authentication needs, but provides substantial operational context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by operational details, then clearly formatted Args and Returns sections. Every sentence adds value—none are redundant or vague—and the structure enhances readability without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (database query with calculations and error handling), no annotations, and no output schema, the description is largely complete: it covers purpose, parameters, behavior, and return values. It could benefit from mentioning prerequisites (e.g., authentication) or performance characteristics, but adequately addresses core functionality and error cases for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema: it explains that 'n' represents 'the number of recent top-ups to sum' with a default of 3, and clarifies it's optional. With 0% schema description coverage (schema only has type and title), the description fully compensates by providing clear parameter meaning and usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('calculates', 'retrieves', 'ensures') and resources ('last n successful top-ups', 'transactions from the database'). It distinguishes from siblings like 'check_balance' (current balance), 'count_topups_by_number' (counts by number), 'get_last_topups' (lists without summing), and 'load_airtime' (different operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for summing recent top-ups, but doesn't explicitly state when to use this tool versus alternatives like 'get_last_topups' (for listing) or 'count_topups_by_number' (for counting by number). It mentions currency consistency as a requirement, which provides some contextual guidance, but lacks explicit when/when-not scenarios or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_balancecount_topups_by_numberget_last_topupsload_airtimesum_last_n_topupsScored across 5 tools
Each tool has a clearly distinct purpose with no overlap: check_balance for account status, load_airtime for sending airtime, and three tools (count_topups_by_number, get_last_topups, sum_last_n_topups) for analyzing transaction history from different angles. The descriptions reinforce these distinct roles, making misselection unlikely.
The naming follows a consistent snake_case pattern with clear verb_noun structures (e.g., check_balance, load_airtime). However, there is a minor deviation: 'count_topups_by_number' uses a prepositional phrase instead of a simple noun, slightly breaking the pattern compared to tools like 'get_last_topups' or 'sum_last_n_topups'.
With 5 tools, the count is well-scoped for an airtime management server. It covers core operations (checking balance, sending airtime) and transaction analysis without being overwhelming, ensuring each tool earns its place in the workflow.
The toolset provides good coverage for airtime operations: checking balance, sending airtime, and analyzing transaction history. A minor gap exists in not having tools for managing transaction errors or refunds, but agents can likely work around this with the existing tools for core workflows.
Prepaid SMS OTP and transactional SMS API. Eight priced markets: NG, GH, KE, ZA, GB, BJ, CI, US.
Send and schedule SMS and WhatsApp messages, manage contacts and templates, and track delivery.
Send, automate, and orchestrate SMS, WhatsApp, Viber, IVR, and USSD messaging in 150+ countries.
Mobile money fees, African tax rates, currency conversion and Uganda PAYE for AI agents.
