{"id":30700757,"url":"https://github.com/sin4ch/mono-mcp","last_synced_at":"2026-05-14T23:31:59.741Z","repository":{"id":311786556,"uuid":"1045028119","full_name":"sin4ch/mono-mcp","owner":"sin4ch","description":"A comprehensive Model Context Protocol (MCP) server for Nigerian banking operations using the Mono Open Banking API.","archived":false,"fork":false,"pushed_at":"2025-08-26T15:07:25.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T20:58:39.745Z","etag":null,"topics":["fastmcp","mcp","openbanking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sin4ch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-26T14:50:12.000Z","updated_at":"2025-08-26T15:07:29.000Z","dependencies_parsed_at":"2025-08-26T20:58:43.811Z","dependency_job_id":"a7d4b309-cd50-4616-997a-b7c1480edf45","html_url":"https://github.com/sin4ch/mono-mcp","commit_stats":null,"previous_names":["sin4ch/mono-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sin4ch/mono-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sin4ch%2Fmono-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sin4ch%2Fmono-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sin4ch%2Fmono-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sin4ch%2Fmono-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sin4ch","download_url":"https://codeload.github.com/sin4ch/mono-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sin4ch%2Fmono-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273287616,"owners_count":25078571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastmcp","mcp","openbanking"],"created_at":"2025-09-02T12:51:48.319Z","updated_at":"2026-05-14T23:31:59.727Z","avatar_url":"https://github.com/sin4ch.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)"],"sub_categories":["MCP Servers"],"readme":"# Mono Banking MCP Server\n\n[![Try on FastMCP Cloud](https://img.shields.io/badge/Try%20on-FastMCP%20Cloud-blue?style=for-the-badge\u0026logo=cloud\u0026logoColor=white)](https://mono-banking-mcp.fastmcp.app/mcp)\n\nA comprehensive **Model Context Protocol (MCP)** server for Nigerian banking operations using the [Mono Open Banking API](https://mono.co). Features integrated webhook support for real-time banking events and seamless deployment on FastMCP Cloud.\n\n## Table of Contents\n\n- [Key Features](#-key-features)\n- [Architecture](#️-architecture)\n- [Technologies Used](#️-technologies-used)\n- [Project Structure](#-project-structure)\n- [Webhook Integration](#-webhook-integration)\n- [Quick Start](#-quick-start)\n- [Usage](#-usage)\n- [Available Banking Tools](#️-available-banking-tools)\n- [Contributing](#-contributing)\n\n## Key Features\n\n- **Complete Banking Operations** - Account management, payments, BVN verification\n- **Real-time Webhooks** - Integrated webhook endpoints for live banking events\n- **AI Assistant Ready** - Seamless integration with Claude, ChatGPT, and other AI assistants\n- **Cloud Deployment** - Ready for FastMCP Cloud with automatic scaling\n- **Enterprise Security** - HMAC signature verification and secure API handling\n- **Event Monitoring** - Built-in webhook event storage and debugging tools\n\n## Architecture\n\n```mermaid\nsequenceDiagram\n    participant User as 👤 User\n    participant AI as 🤖 AI Assistant\u003cbr/\u003e(Claude/ChatGPT)\n    participant MCP as ⚡ MCP Server\u003cbr/\u003e(FastMCP + Webhooks)\n    participant Client as 🔗 Mono Client\u003cbr/\u003e(httpx)\n    participant API as 🏦 Mono API\u003cbr/\u003e(Nigerian Banks)\n    participant Webhook as 📡 Webhook Events\n\n    User-\u003e\u003eAI: \"Check my account balance\"\n    AI-\u003e\u003eMCP: list_tools()\n    MCP--\u003e\u003eAI: 12 banking tools + webhook monitoring\n\n    AI-\u003e\u003eMCP: get_account_balance(account_id)\n    MCP-\u003e\u003eClient: get_account_balance(account_id)\n    Client-\u003e\u003eAPI: GET /accounts/{id}/balance\n    API--\u003e\u003eClient: {\"balance\": 50000, \"currency\": \"NGN\"}\n    Client--\u003e\u003eMCP: Account balance data\n    MCP--\u003e\u003eAI: {\"success\": true, \"balance\": \"₦500.00\"}\n    AI--\u003e\u003eUser: \"Your account balance is ₦500.00\"\n\n    Note over Webhook,MCP: Real-time Events\n    API-\u003e\u003eMCP: POST /mono/webhook (account.updated)\n    MCP-\u003e\u003eMCP: Verify HMAC signature\n    MCP-\u003e\u003eMCP: Store event in database\n```\n\n## Technologies Used\n\n- **Python 3.12+** - Modern Python with async/await support\n- **FastMCP 2.12+** - Simplified MCP server with custom route support\n- **Starlette** - ASGI framework for webhook endpoints\n- **httpx** - Modern async HTTP client for API communication\n- **SQLAlchemy** - Database ORM for webhook event storage\n- **Mono Open Banking API v2** - Nigerian banking infrastructure\n- **python-dotenv** - Environment variable management\n- **uv** - Fast Python package manager (recommended)\n\n## Project Structure\n\n```\nmono-banking-mcp/\n├── mono_banking_mcp/           # Main package\n│   ├── server.py                 # FastMCP server with 12 tools + webhook endpoints\n│   ├── mono_client.py            # Mono API client with async httpx\n│   └── database.py               # SQLAlchemy database for webhook events storage\n├── tests/                     # Comprehensive test suite with webhook integration tests\n│   ├── conftest.py               # Test configuration and fixtures\n│   └── test_mono_banking.py      # Unit and integration tests\n├── pyproject.toml            # Modern Python project configuration (uv-based)\n├── uv.lock                   # Dependency lock file with FastMCP 2.12+\n├── pytest.ini               # Test configuration and markers\n├── Makefile                  # Development workflow automation with webhook commands\n├── README.md                 # This comprehensive documentation\n└── .env.example              # Environment variables template\n```\n\n## Webhook Integration\n\n### Real-time Event Processing\n\nThe server includes integrated webhook support for real-time banking events:\n\n```mermaid\ngraph LR\n    A[Mono API] --\u003e|POST /mono/webhook| B[FastMCP Server]\n    B --\u003e|HMAC Verify| C[Signature Check]\n    C --\u003e|✅ Valid| D[Store Event]\n    C --\u003e|❌ Invalid| E[Reject]\n    D --\u003e F[SQLite Database]\n    F --\u003e G[get_webhook_events Tool]\n    G --\u003e H[AI Assistant]\n```\n\n###  Key Integration Points\n\n- **`/mono/webhook`** - Webhook endpoint for real-time Mono events\n- **`/health`** - Health check endpoint for monitoring\n\n### Supported Webhook Events\n\n- **`account.connected`** - New account linked\n- **`account.updated`** - Account information changed\n- **`account.unlinked`** - Account disconnected\n- **`job.completed`** - Data sync completed\n- **`job.failed`** - Data sync failed\n\n### Security Features\n\n- **HMAC-SHA256 Signature Verification** - Ensures webhook authenticity\n- **Environment-based Secrets** - Secure credential management\n- **Request Validation** - Malformed request rejection\n- **Event Storage** - Audit trail for all webhook events\n\n## Quick Start\n\n**Ready to use immediately!** Connect your AI assistant to:\n\n[![Try on FastMCP Cloud](https://img.shields.io/badge/Try%20Now-FastMCP%20Cloud-blue?style=for-the-badge\u0026logo=cloud\u0026logoColor=white)](https://mono-banking-mcp.fastmcp.app/mcp)\n\n```\nhttps://mono-banking-mcp.fastmcp.app/mcp\n```\n\n### Available Endpoints\n\n- **MCP Server**: `https://mono-banking-mcp.fastmcp.app/mcp`\n- **Webhook Endpoint**: `https://mono-banking-mcp.fastmcp.app/mono/webhook`\n- **Health Check**: `https://mono-banking-mcp.fastmcp.app/health`\n\n## Usage\n\n### Claude Desktop Integration\n\nAdd to your Claude Desktop configuration (`~/.config/claude-desktop/config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mono-banking\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-fetch\", \"https://mono-banking-mcp.fastmcp.app/mcp\"]\n    }\n  }\n}\n```\n\n### Usage Examples\n\nOnce connected to an AI assistant (Claude, Gemini, etc.), you can use natural language commands:\n\n#### Account Management\n- *\"List all my linked bank accounts\"*\n- *\"Show me the balance for account abc123\"*\n- *\"Get detailed information for my GTBank account\"*\n- *\"Show me the last 20 transactions for account xyz789\"*\n\n#### Payment Operations\n- *\"Verify the account name for 0123456789 at GTBank (code 058)\"*\n- *\"Initiate a payment of ₦5000 to account 1234567890 at Access Bank for John Doe\"*\n- *\"Check the status of payment reference PAY_ABC123\"*\n\n#### Banking Information\n- *\"Show me all supported Nigerian banks and their codes\"*\n- *\"Look up BVN 12345678901 for identity verification\"*\n- *\"Help a new customer link their bank account\"*\n\n#### Complete Workflow Example\n1. *\"Show me all Nigerian banks\"* - Get bank codes\n2. *\"Verify account 1234567890 at Access Bank\"* - Confirm recipient\n3. *\"Initiate payment of ₦10000 to verified account for rent payment\"* - Start payment\n4. *\"Check payment status for the reference you just gave me\"* - Verify completion\n\n## Available Banking Tools\n\nThe server provides these comprehensive banking tools (**12 total**):\n\n### Core Banking Operations\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_linked_accounts` | List all linked bank accounts | None |\n| `get_account_balance` | Get current account balance | `account_id` |\n| `get_account_info` | Get basic account information | `account_id` |\n| `get_account_details` | Get comprehensive account details including BVN | `account_id` |\n| `get_transaction_history` | Retrieve transaction records with pagination | `account_id`, `limit`, `page` |\n| `verify_account_name` | Verify recipient account details before payments | `account_number`, `bank_code` |\n| `initiate_payment` | Start a payment via Mono DirectPay | `amount`, `recipient_account_number`, `recipient_bank_code`, customer info |\n| `verify_payment` | Check payment status using reference | `reference` |\n| `get_nigerian_banks` | List all supported Nigerian banks with codes | None |\n| `lookup_bvn` | Perform BVN identity verification | `bvn`, `scope` |\n| `initiate_account_linking` | Start account linking process for new customers | `customer_name`, `customer_email` |\n\n## Contributing\n\nContributions to the Mono Banking MCP Server are welcome! For questions or help getting started, please open an issue.\n\n### Development Workflow\n\n**Quick Start for Contributors:**\n```bash\n# Fork and clone the repository\ngit clone https://github.com/YOUR_USERNAME/mono-banking-mcp.git\ncd mono-banking-mcp\n\n# Set up development environment\nuv sync\nuv pip install -e .\n\n# Verify installation with webhook support\npython -c \"from mono_banking_mcp.server import mcp; print('✅ Package installed successfully')\"\n\n# Run comprehensive tests\nmake test-all\n\n# Create feature branch and start developing\ngit checkout -b feature/your-feature-name\n\n# Test your changes\nmake test-webhook  # Test webhook functionality\nmake tools         # Verify all 12 tools are working\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsin4ch%2Fmono-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsin4ch%2Fmono-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsin4ch%2Fmono-mcp/lists"}