Provides MongoDB integration for tracking orders, storing user profiles, and managing order lifecycle states such as PENDING, CONFIRMED, IN_TRANSIT, and DELIVERED.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BulkClix MCP Server what's my wallet balance?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Python-based MCP (Model Context Protocol) server that gives AI agents (LibreChat, Claude Desktop, Cursor, etc.) full access to ghanaian platforms via natural language.
Developed with FastMCP for simple tool declarations.
Food & Catalog Ordering: Search food menus across Accra/Bolt Food catalog, place merchant orders via SMS, collect MoMo payments.
MongoDB Order Tracking: Save user profiles, delivery addresses, and track live order lifecycle states (PENDING, CONFIRMED, IN_TRANSIT, DELIVERED).
SMS: Send bulk SMS, fetch campaign reports, request/list Sender IDs.
OTP: Send and verify OTPs via SMS and Email.
Airtime: List networks, purchase airtime via momo, and send airtime from wallet balance.
Mobile Money: MoMo payment collections, status checks, disbursements.
Bank Transfer: Disburse to bank accounts, list banks.
Data Bundles: Fetch bundles, purchase data packages.
KYC: MSISDN owner name lookups.
Contacts: Full CRUD for contact groups & contacts.
Account: Check wallet balance.
Related MCP server: AgentPhone MCP Server
Run the server along with the mini MongoDB instance for tracking orders and storing user profiles:
docker-compose up -dUsing uv is highly recommended as it automatically manages dependencies:
# Run server using uv
uv run server.pyIf you want the server to use a default BulkClix key, set BULKCLIX_API_KEY before starting it:
export BULKCLIX_API_KEY="your-bulkclix-api-key"
uv run server.py mcpTo expose admin-only workflows like contact management, enable internal tools on the server:
export BULKCLIX_ENABLE_INTERNAL_TOOLS=trueThe public chat-facing tools now work without caller-supplied keys. SMS and OTP tools automatically pick the first sender ID returned by BulkClix. Airtime and data purchases first collect payment through MoMo, then complete the fulfillment after payment is confirmed.
Add this under mcpServers in your librechat.yaml:
mcpServers:
ananse:
command: uv
args:
- run
- --directory
- /path/to/ananse-mcp
- server.py
type: stdioRun the server on a port (e.g. port 8000):
cd ananse-mcp
uv run server.py mcpThen configure LibreChat to use the MCP-over-HTTP endpoint:
mcpServers:
bulkclix:
url: http://localhost:8000/
type: sseYou can then tunnel that port with localtunnel:
npx localtunnel --port 8000If BULKCLIX_API_KEY is set on the machine running the server, the client can use the public tools without providing any per-call key.
Admin-only tools are hidden unless BULKCLIX_ENABLE_INTERNAL_TOOLS=true is set on the server.
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0). See the LICENSE file for details.
Get supported networks for airtime top-up.
Inputs: no named parameters. Returns: object
Start an airtime purchase using the BulkClix purchase route. :param destination: Recipient phone number receiving the airtime. :param phone_number: MoMo phone number being charged for payment. :param network: Payer network code (e.g., 'MTN', 'VDF', 'ATL'). :param amount: Airtime purchase amount in GHS. :param network_id: Network UUID from airtime_get_networks. :param payment_type: Payment type (usually 'momo').
Inputs: amount (required), network (required), network_id (required), destination (required), +8 more. Returns: object
Place an order with a food/goods vendor and initiate mobile money payment via BulkClix. IMPORTANT: Before calling this tool you MUST have collected ALL required fields from the user: (1) if order_type='inhouse' — you MUST ask the user for their table_number first; (2) if order_type='delivery' — you MUST ask the user for their delivery_address first. Do NOT call this tool without those values — the tool will fail. :param vendor_id: Vendor's UUID. :param items: List of items to order, with dish_id, quantity, and addon_ids. :param payment_number: Mobile money number to charge (e.g. '0544929180'). :param network: Mobile money network code (e.g. 'MTN'). :param order_type: 'inhouse' or 'delivery' — must be one of the vendor's supported order_types. :param table_number: Table number string. REQUIRED when order_type is 'inhouse' — ask the user before calling. :param delivery_address: Delivery address string. REQUIRED when order_type is 'delivery' — ask the user before calling. :returns: dict with success, order_id, payment status, and vendor confirmation.
Inputs: items (required), network (required), vendor_id (required), payment_number (required), +3 more. Returns: object
Check the status of a data bundle payment or purchase by order ID.
Inputs: order_id (required), payment_id, transaction_id. Returns: object
List available data bundle services.
Inputs: network_id. Returns: object
List available data bundle offers for a service and phone number. :param service_id: Data service UUID. :param phone_number: Recipient phone number.
Inputs: service_id (required), phone_number (required). Returns: object
Start a data bundle purchase using the BulkClix purchase route.
Inputs: network (required), bundle_id (required), network_id (required), service_id (required), +8 more. Returns: object
Search for food items, dishes, pizza, rice, chicken, or menus across all verified vendors or a specific vendor. Use this when asking 'what food is available', 'show me the menu', 'do you have pizza', 'search menu for burger'.
Inputs: query (required), vendor_id. Returns: object
Retrieve a saved customer profile from MongoDB by phone number to get delivery address and payment preferences.
Inputs: phone_number (required). Returns: object
Returns information about the Auth0 token.
Inputs: no named parameters. Returns: object
List available vendors to purchase goods from using BulkClix payment. :param vendor_id: Vendor's UUID. If given, returns just that vendor. :param category: Vendor's category of goods (e.g. 'restaurant', 'food', 'airtime'). If given, filters vendors using case-insensitive substring and synonym expansion.
Inputs: category, vendor_id. Returns: object
Get a Yango booking link for a delivery between two points. The customer opens this link to confirm pickup/dropoff and pricing in the Yango app — pricing and order placement happen on Yango's side, not through this server, until direct API access is enabled.
Inputs: pickup_lat (required), pickup_lon (required), dropoff_lat (required), dropoff_lon (required). Returns: object
List all categories of goods (e.g. 'restaurant', 'food', 'airtime', 'data') supported by the verified vendors.
Inputs: no named parameters. Returns: object
Check the status of a Mobile Money collection or transaction. :param transaction_id: The transaction ID returned during collection. :param payment_id: Optional payment record ID if you already have it.
Inputs: transaction_id (required), payment_id. Returns: object
Send an OTP (One-Time Password) via Email. CRITICAL: The message parameter MUST contain the exact placeholder <%otp_code%>. If this placeholder is missing, the API call will fail with a 422 error. :param email: Recipient email address. :param subject: Email subject. :param message: Email body containing <%otp_code%> template (e.g. 'Your verification code is: <%otp_code%>'). :param expiry: OTP validity duration in minutes (default 5). :param length: Digit length of the OTP (default 4).
Inputs: email (required), message (required), subject (required), expiry, +1 more. Returns: object
Send an OTP (One-Time Password) via SMS. CRITICAL: The message parameter MUST contain the exact placeholder <%otp_code%>. If this placeholder is missing, the API call will fail with a 422 error. :param phone_number: Recipient phone number (e.g. '0541000000'). :param message: Message template containing <%otp_code%> (e.g. 'Your verification code is: <%otp_code%>'). :param expiry: OTP validity duration in minutes (default 5). :param length: Digit length of the OTP (default 4).
Inputs: message (required), phone_number (required), expiry, length. Returns: object
Verify an OTP code that was sent via Email. :param request_id: The requestId returned from sending the OTP. :param email: The email address the OTP was sent to. :param code: The verification code to verify.
Inputs: code (required), email (required), request_id (required). Returns: object
Verify an OTP code that was sent via SMS. :param request_id: The requestId returned from sending the OTP. :param phone_number: The phone number the OTP was sent to. :param code: The code input by the user to check.
Inputs: code (required), request_id (required), phone_number (required). Returns: object
Verify a payment OTP after the customer reads the code from their phone and sends it in chat. CRITICAL: This is ONLY for validating payment-related transactions. The request_id MUST be the one returned in the response of a payment/purchase initiation tool (e.g., airtime_purchase, data_purchase, or momo_collect), NOT from otp_send_sms. Providing a standard SMS OTP request ID will result in a 404 Error. :param code: OTP code entered by the customer from their phone. :param request_id: Request ID returned from the payment/purchase initiation response. :param phone_number: The phone number used for the payment transaction.
Inputs: code (required), request_id (required), phone_number (required). Returns: object
Place a food order directly with a restaurant merchant. Creates an order record in MongoDB, triggers MoMo payment collection from customer, and sends an order SMS dispatch to the merchant.
Inputs: items (required), amount_ghc (required), customer_name (required), customer_phone (required), +4 more. Returns: object
Save or update a customer profile in MongoDB, including delivery address, landmark, and default MoMo payment number.
Inputs: address (required), phone_number (required), customer_name (required), landmark, +1 more. Returns: object
Search for vendors (merchants), menu items, and MCP tools/capabilities semantically in a single query. Use this to resolve which tool to call, which vendor fits a concept, or what food/goods are available.
Inputs: query (required), top_n, vendor_id. Returns: object
Track real-time status and delivery details of an order from MongoDB.
Inputs: order_id (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Tools have distinct purposes overall, but there is overlap among search tools (find_food_items, search_food_menus, search) and between order placement tools (create_verified_vendors_order, place_merchant_order). Descriptions help differentiate, but an agent might still misselect.
Most tools follow a verb_noun snake_case pattern (e.g., airtime_get_networks, data_purchase). However, there are minor deviations: 'pay_verify_otp' uses two verbs, and 'search' lacks a noun. Overall, the convention is fairly consistent.
With 25 tools, the server covers multiple domains (airtime, data, food ordering, OTP, profiles, search). This is slightly heavy but not excessive given the scope. Some tools could be consolidated (e.g., merging similar search tools).
The tool surface supports core workflows: airtime/data top-up, food ordering with payment, OTP verification, and customer profiles. Missing update/delete operations for orders and profiles are minor gaps; no dead ends for main use cases.
Business texting for AI agents: send texts, read threads, manage contacts and run campaigns.
Create and manage DialNexa AI voice agents, campaigns, calls, phone numbers, workflows, and more.
Give any AI agent a phone: make and answer calls, get through phone menus, and send texts.
Read BulkSMS messages, replies, profile and webhooks; send SMS to up to 10 numbers.
