kuda-mcp

MCP server for the Kuda Bank Open Banking API. Enables AI assistants like Claude to manage virtual accounts, process transfers, pay bills, manage savings, and more through Nigeria's leading digital bank.

Features

• Account Management - Create, update, enable/disable virtual accounts, check balances
• Fund Transfers - Bank list lookup, name enquiry, single/bulk transfers from main or virtual accounts
• Transaction History - View and filter transactions for main and virtual accounts
• Bill Payments - Purchase airtime, data, electricity, cable TV, betting from any supported biller
• Savings - Create and manage plain, flexible, and fixed savings accounts
• Card Management - Request, activate, block/unblock cards, manage PINs and limits
• Gift Cards - Browse, purchase, and check status of gift cards

Prerequisites

1. A Kuda Business account
2. API credentials (email + API key) from your Kuda Business dashboard
3. Node.js 18+

Installation

Using npx (recommended)

npx kuda-mcp

Global install

npm install -g kuda-mcp
kuda-mcp

Build from source

git clone https://github.com/samaxbytez/kuda-mcp.git
cd kuda-mcp
npm install
npm run build

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | KUDA_EMAIL | Yes | Your Kuda Business API email | | KUDA_API_KEY | Yes | Your Kuda API key from the dashboard | | KUDA_BASE_URL | No | API base URL (defaults to sandbox: https://kuda-openapi-uat.kudabank.com/v2.1) |

Base URLs

| Environment | URL | |-------------|-----| | Sandbox/UAT | https://kuda-openapi-uat.kudabank.com/v2.1 | | Production | https://kuda-openapi.kuda.com/v2.1 |

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kuda": {
      "command": "npx",
      "args": ["-y", "kuda-mcp"],
      "env": {
        "KUDA_EMAIL": "[email protected]",
        "KUDA_API_KEY": "your_api_key_here",
        "KUDA_BASE_URL": "https://kuda-openapi-uat.kudabank.com/v2.1"
      }
    }
  }
}

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "kuda": {
      "command": "npx",
      "args": ["-y", "kuda-mcp"],
      "env": {
        "KUDA_EMAIL": "[email protected]",
        "KUDA_API_KEY": "your_api_key_here",
        "KUDA_BASE_URL": "https://kuda-openapi-uat.kudabank.com/v2.1"
      }
    }
  }
}

Architecture

kuda-mcp/
├── src/
│   ├── index.ts              # Entry point, server setup
│   ├── client.ts             # Kuda API client (single-URL architecture)
│   ├── utils.ts              # Shared utilities (response helpers, logging)
│   ├── client.test.ts        # Client tests
│   ├── utils.test.ts         # Utils tests
│   └── tools/
│       ├── accounts.ts       # Virtual account management (10 tools)
│       ├── transfers.ts      # Bank transfers & payments (9 tools)
│       ├── transactions.ts   # Transaction history (5 tools)
│       ├── bills.ts          # Bill payments (7 tools)
│       ├── savings.ts        # Savings management (16 tools)
│       ├── cards.ts          # Card management (9 tools)
│       ├── gift-cards.ts     # Gift cards (4 tools)
│       └── tools.test.ts     # Tool handler tests
├── package.json
├── tsconfig.json
└── smithery.yaml

The Kuda API uses a unique single-URL architecture where all requests are POST to the same endpoint, with the operation determined by a serviceType field in the request body. The client handles token management, automatic retry on 401, and JSON-encoded payload wrapping.

Tools Reference

Account Management (10 tools)

| Tool | Description | |------|-------------| | kuda_create_virtual_account | Create a new virtual account | | kuda_update_virtual_account | Update virtual account details | | kuda_get_virtual_accounts | List all virtual accounts (paginated) | | kuda_get_virtual_account | Get a specific virtual account | | kuda_disable_virtual_account | Deactivate a virtual account | | kuda_enable_virtual_account | Reactivate a virtual account | | kuda_get_main_account_balance | Get main account balance | | kuda_get_virtual_account_balance | Get virtual account balance | | kuda_upgrade_virtual_account | Upgrade a virtual account tier | | kuda_update_virtual_account_limit | Update transfer limits |

Fund Transfers (9 tools)

| Tool | Description | |------|-------------| | kuda_get_banks | List all Nigerian banks and codes | | kuda_name_enquiry | Verify account holder name before transfer | | kuda_fund_transfer | Transfer from main account | | kuda_virtual_account_fund_transfer | Transfer from virtual account | | kuda_get_transaction_status | Check transfer status | | kuda_fund_virtual_account | Fund virtual account from main | | kuda_withdraw_virtual_account | Withdraw from virtual to main | | kuda_process_transfers | Process bulk transfer instructions | | kuda_search_transfer_instructions | Search transfer instruction status |

Transaction History (5 tools)

| Tool | Description | |------|-------------| | kuda_get_main_account_transactions | List main account transactions | | kuda_get_main_account_filtered_transactions | Filter by date range | | kuda_get_virtual_account_transactions | List virtual account transactions | | kuda_get_virtual_account_filtered_transactions | Filter by date range | | kuda_get_transaction_logs | Get transaction logs |

Bill Payments (7 tools)

| Tool | Description | |------|-------------| | kuda_get_billers_by_type | List billers (airtime, electricity, etc.) | | kuda_verify_bill_customer | Verify customer before bill purchase | | kuda_purchase_bill | Pay bill from main account | | kuda_purchase_bill_virtual_account | Pay bill from virtual account | | kuda_get_bill_purchase_status | Check bill payment status | | kuda_get_purchased_bills | List bills paid from main account | | kuda_get_purchased_bills_virtual_account | List bills paid from virtual |

Savings (16 tools)

| Tool | Description | |------|-------------| | kuda_create_plain_savings | Create plain savings account | | kuda_get_plain_savings | Get specific plain savings | | kuda_get_all_plain_savings | Get all plain savings | | kuda_plain_savings_credit_debit | Credit/debit plain savings | | kuda_get_plain_savings_transactions | Get plain savings transactions | | kuda_create_flexible_savings | Create open flexible savings | | kuda_pre_create_flexible_savings | Pre-create flexible savings | | kuda_get_flexible_savings | Get specific flexible savings | | kuda_get_all_flexible_savings | Get all flexible savings | | kuda_withdraw_flexible_savings | Withdraw from flexible savings | | kuda_get_flexible_savings_transactions | Get flexible savings transactions | | kuda_create_fixed_savings | Create fixed savings | | kuda_get_fixed_savings | Get specific fixed savings | | kuda_get_all_fixed_savings | Get all fixed savings | | kuda_close_fixed_savings | Close fixed savings and withdraw | | kuda_get_fixed_savings_transactions | Get fixed savings transactions |

Card Management (9 tools)

| Tool | Description | |------|-------------| | kuda_request_card | Request a new debit card | | kuda_get_customer_cards | List customer's cards | | kuda_activate_card | Activate a new card | | kuda_deactivate_card | Deactivate a card | | kuda_set_card_limit | Set card spending limit | | kuda_manage_card_channel | Manage card channels (ATM/POS/Web) | | kuda_change_card_pin | Change card PIN | | kuda_block_card | Block a card | | kuda_unblock_card | Unblock a card |

Gift Cards (4 tools)

| Tool | Description | |------|-------------| | kuda_get_gift_cards | List available gift cards | | kuda_buy_gift_card | Buy from main account | | kuda_buy_gift_card_virtual_account | Buy from virtual account | | kuda_get_gift_card_status | Check purchase status |

Example Prompts

• "What's my main account balance?"
• "List all my virtual accounts"
• "Create a virtual account for John Doe with email [email protected]"
• "What banks are available for transfers?"
• "Verify account number 1234567890 at GTBank before I transfer"
• "Transfer 5000 naira from my main account to account 1234567890 at Access Bank"
• "Show me my transactions from January 2026"
• "Buy 1000 naira airtime for 08012345678"
• "What electricity billers are available?"
• "Create a plain savings account called 'Emergency Fund'"

Development

# Install dependencies
npm install

# Type check
npm run type-check

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

Adding New Tools

1. Create a new file in src/tools/ or add to an existing category
2. Follow the pattern: register function, zod schema, logToolCall, try/catch with jsonResponse/errorResponse
3. Import and register in src/index.ts
4. Add tests in src/tools/tools.test.ts

Troubleshooting

"Missing required environment variables"

Ensure KUDA_EMAIL and KUDA_API_KEY are set. Check your Kuda Business dashboard for credentials.

"Authentication failed" or 401 errors

Your API key may have expired or be incorrect. Generate a new key from the Kuda dashboard.

"WARNING: Running against PRODUCTION Kuda API"

You've set KUDA_BASE_URL to the production endpoint. This is intentional for live operations but use sandbox for testing.

Transfers failing with "Name enquiry required"

Always call kuda_name_enquiry before making a transfer. The session ID from the response is required.

"HTTP 500 error"

This is a server-side Kuda error. Check the Kuda status page or retry after a few minutes.

Sandbox vs Production differences

Bank lists and behavior may differ between sandbox and production. Always test thoroughly before going live.

License

MIT