ShegerPay MCP Server

Model Context Protocol (MCP) server for ShegerPay — the African payment gateway. Lets AI assistants (Claude Code, Claude Desktop, Codex, Gemini CLI, Cline, Cursor, or anything else that speaks MCP) verify Ethiopian payments, manage payment links and webhooks, and build integrations against your account.

Access modes — read this before connecting an agent

An MCP server hands these tools to an AI agent, and an agent cannot reliably tell your instructions apart from text it merely read — a customer name, a webhook payload, a scraped web page. That is prompt injection, and here the blast radius is money leaving your account — a refund or a card charge has no undo.

So capability is opt-in. Set SHEGERPAY_MCP_MODE:

| Mode | Tools | What an agent can do | |---|---|---| | readonly | 19 | Verify payments, read history, prices, balances, analytics. Changes nothing. | | standard (default) | 32 | The above, plus create/update payment links, webhooks, crypto payments, PayPal orders. Cannot move money. | | full | 40 | The above, plus refunds, charging saved cards, API-key management, password change. |

Platform-admin tools (admin_list_users, admin_approve_payout, admin_get_platform_stats) and the payout tools are never exposed at any mode — they act across merchants, so no single merchant's agent should reach them.

Tools above the active mode are not listed at all, so an agent cannot be talked into calling something it never saw. Direct calls are refused too.

Recommendation: start on readonly while an agent is exploring. Move to standard to let it build a real integration. Use full only for a session you are actively watching, and pair it with an API key scoped to just what you need — the key is the real security boundary; the mode is a guardrail on top of it.

Payouts are not available

ShegerPay verifies payments; it does not hold merchant funds. Money moves straight from your customer to your bank, so there is no ShegerPay balance to withdraw and the payout endpoints answer 501 PAYOUTS_DISABLED. The payout tools are not exposed at any mode.

Setup

{
  "mcpServers": {
    "shegerpay": {
      "command": "npx",
      "args": ["-y", "@shegerpay/mcp-server"]
    }
  }
}

No API key. Ask your agent to do anything with ShegerPay and it will hand you a link and a code. Approve once, and it is connected for good — the key is saved to ~/.shegerpay/mcp-credentials.json, never pasted anywhere.

You:   verify CBE payment FT26082ABC123
Agent: Approve here: https://shegerpay.com/link?code=89XV-BV5B
       (you click, choose what it may do, approve)
Agent: Connected. Verifying...

Setting SHEGERPAY_API_KEY still works if you prefer to supply one, or for CI.

Any MCP-capable agent uses the same command; only the config file location differs.

Features

🎯 Core Payment Verification

• Ethiopian Banks: Verify CBE, Telebirr, Awash Bank, Bank of Abyssinia, E-Birr payments
• Quick Verify: Auto-detect provider from transaction ID
• Payment History: Complete transaction history with filters

₿ Cryptocurrency Support

• Real-time Prices: Get live crypto prices for USDT, ETH, BNB, TRX
• Create Payments: Generate crypto payment intents with exact amounts
• Verify Transactions: On-chain verification via blockchain APIs
• Networks: TRC20, ERC20, BEP20, native chains

💳 PayPal Integration

• Orders: Create and capture PayPal payments
• Refunds: Full and partial refund support
• Subscriptions: Manage recurring payments
• Card Vaulting: Save cards for one-click checkout

🔗 Payment Links

• Create Links: Generate shareable payment links with QR codes
• Analytics: Track views, payments, conversion rates
• Multi-Method: Support multiple payment methods per link

🪝 Webhooks

• Real-time Notifications: Receive instant payment updates
• Event Types: payment.verified, refund.created, dispute.opened, etc.
• HMAC Signatures: Secure webhook verification

💰 Multi-Currency Wallets

• Balance Tracking: ETB, USD, EUR, and crypto balances
• Currency Conversion: Convert between fiat and crypto

🔑 Account Management

• API Keys: Generate test and live mode keys
• Usage Stats: Monitor API usage and quotas
• Subscription: View plan details and limits

👑 Admin Tools

Not exposed over MCP at any mode — they act across merchants.

Installation

For AI Assistants (Claude Desktop, Cline, Vibe Coder)

1. Install the package:

npm install -g @shegerpay/mcp-server

2. Get your ShegerPay API key:

   • Sign up at shegerpay.com
   • Go to Settings → API Keys
   • Generate a new API key (test or live mode)

3. Configure your AI assistant:

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shegerpay": {
      "command": "npx",
      "args": ["-y", "@shegerpay/mcp-server"],
      "env": {
        "SHEGERPAY_API_KEY": "sk_test_your_api_key_here"
      }
    }
  }
}

Cline (VS Code Extension)

Add to Cline MCP settings:

{
  "shegerpay": {
    "command": "npx",
    "args": ["-y", "@shegerpay/mcp-server"],
    "env": {
      "SHEGERPAY_API_KEY": "sk_test_your_api_key_here"
    }
  }
}

Vibe Coder

Add to Vibe Coder MCP configuration:

{
  "mcpServers": {
    "shegerpay": {
      "command": "npx",
      "args": ["-y", "@shegerpay/mcp-server"],
      "env": {
        "SHEGERPAY_API_KEY": "sk_test_your_api_key_here"
      }
    }
  }
}

4. Restart your AI assistant to load the MCP server

Usage Examples

Once configured, you can interact with ShegerPay using natural language:

Verify Ethiopian Payments

"Verify transaction FT241227ABC123 for 500 ETB"
"Quick verify this Telebirr payment: TB123456789"
"Show me my payment history from last week"

Crypto Operations

"What's the current USDT price?"
"Create a crypto payment for $100 in USDT TRC20"
"Verify this crypto transaction: 0x123abc..."

Payment Links

"Create a payment link for 1000 ETB with title 'Product Invoice'"
"Show analytics for payment link link_abc123"
"List all my active payment links"

Webhooks

"Register a webhook for payment.verified events to https://myapp.com/webhook"
"Test my webhook at https://myapp.com/webhook"
"List all my webhooks"

Wallet Management

"Show my wallet balances"
"Convert 100 USD to ETB in my wallet"

Account Management

"Generate a new test API key"
"Show my current subscription status"
"What's my API usage this month?"

Admin Operations (Admin only)

"Show platform statistics"

Available Tools

The MCP server provides 40+ tools organized into categories:

Core Verification (3 tools)

• verify_payment - Verify Ethiopian bank payment
• quick_verify - Auto-detect and verify
• get_payment_history - Retrieve verification history

Crypto (4 tools)

• get_crypto_prices - Get all crypto prices
• get_crypto_price - Get specific crypto price
• create_crypto_payment - Generate crypto payment intent
• verify_crypto_payment - Verify blockchain transaction

PayPal (5 tools)

• create_paypal_order - Create PayPal order
• capture_paypal_order - Capture payment
• refund_payment - Process refund
• list_saved_cards - Get vaulted cards
• charge_saved_card - One-click payment

Payment Links (4 tools)

• create_payment_link - Generate payment link
• list_payment_links - List all links
• get_payment_link_analytics - Link analytics
• delete_payment_link - Delete link

Webhooks (4 tools)

• create_webhook - Register webhook
• list_webhooks - List webhooks
• test_webhook - Test endpoint
• delete_webhook - Delete webhook

Wallets (4 tools)

• get_wallet_balances - All balances
• convert_currency - Currency conversion

Transactions (2 tools)

• get_transaction_history - Complete history
• export_transactions - Export to CSV/JSON

API Keys (3 tools)

• generate_api_key - Create new key
• list_api_keys - List all keys
• revoke_api_key - Delete key

Account (3 tools)

• get_account_settings - Account info
• get_subscription_status - Plan details
• get_usage_stats - Usage metrics

Admin (3 tools)

• admin_get_platform_stats - Platform metrics
• admin_list_users - All users

Environment Variables

• SHEGERPAY_API_KEY (required) - Your ShegerPay API key (test or live)
• SHEGERPAY_BASE_URL (optional) - API base URL (default: https://api.shegerpay.com)

API Key Modes

ShegerPay supports two API key modes:

• Test Mode: sk_test_... - Use for testing without real money
• Live Mode: sk_live_... - Use for production payments

The MCP server automatically detects the mode from your API key.

Security

• API keys are never logged - Only used for authentication
• Secure by default - All API calls use HTTPS
• Environment-based - Keys stored in environment variables, not code
• Webhook signatures - HMAC-SHA256 verification for webhooks

Development

Local Development

1. Clone the repository:

git clone https://github.com/shegerpay/shegerpay-mcp.git
cd shegerpay-mcp

2. Install dependencies:

npm install

3. Create .env file:

SHEGERPAY_API_KEY=sk_test_your_key_here
SHEGERPAY_BASE_URL=https://api.shegerpay.com

4. Build:

npm run build

5. Test locally:

node dist/index.js

Publishing Updates

npm version patch  # or minor, major
npm publish

Support

• Documentation: shegerpay.com/docs
• Email: [email protected]
• Telegram: @shegerpay0
• Telegram Channel: @shegerPa

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License - see LICENSE for details

About ShegerPay

ShegerPay is the leading payment gateway for African businesses, providing seamless payment verification for:

• 🇪🇹 Ethiopian banks (CBE, Telebirr, Awash, BoA, E-Birr)
• 🌍 International payments (PayPal, Wise, Payoneer, Bank transfers)
• ₿ Cryptocurrency (USDT, ETH, BNB, TRX on multiple networks)

Join thousands of businesses using ShegerPay to accept payments from anywhere in the world.

Made with ❤️ by the ShegerPay Team