High-Level Architecture

The MBBank MCP (Model Context Protocol) server is designed to provide an interface between Large Language Models (LLMs) and the MBBank API. It leverages the mbbank-lib library to facilitate account monitoring, transaction analytics, and balance checking through a standardized protocol.

The system operates as a bridge, translating high-level tool calls from MCP clients into specific asynchronous API requests to MBBank's infrastructure. It supports both standard input/output (stdio) for local integration and Server-Sent Events (SSE) for remote web-based interactions.

Sources: README.md:1-5, pyproject.toml:11-20, mbbank_mcp/core.py:19-25

System Components

The architecture consists of three primary layers: the Entry Point/CLI, the MCP Server Core, and the Data Transformation Layer.

Entry Point and Initialization

The application is initialized via a CLI interface that handles authentication and server configuration. It validates user credentials (username and password) provided either via command-line arguments or environment variables.

The server checks for the existence of MBBANK_USERNAME and MBBANK_PASSWORD before initiating the MBBankAsync client and starting the server loop.

Sources: mbbank_mcp/main.py:26-55, README.md:43-51

MCP Server Core (core.py)

The core logic resides in the crate_mcp_server function, which initializes a FastMCP instance and registers various banking tools. These tools allow the LLM to interact with bank balances, transactions, and savings information.

Sources: mbbank_mcp/core.py:19-30, mbbank_mcp/init.py:1-1

Transfer Workflow and State Management

A critical part of the architecture is the handling of money transfers. To ensure security, the system implements a two-step verification process involving QR code generation and OTP validation.

Transfer Sequence

The system uses a temporary TransferState to manage the lifecycle of a transfer session, which expires after 120 seconds to maintain security.

The server utilizes asyncio.create_task to run a background cleanup routine that removes expired transfer sessions from the transfer_manager.

Sources: mbbank_mcp/core.py:32-108

Data Modeling and Normalization

The server uses Pydantic models in modals.py to act as a proxy layer. This renames raw API fields from the mbbank-lib response into more descriptive, developer-friendly names.

Key Data Structures

• AccountModel: Represents standard and international bank accounts.
• TransactionModel: Normalizes transaction history, including credit/debit formatting.
• SavingModel: Distinguishes between Online Savings (OSA) and Branch Savings (SBA).

Sources: mbbank_mcp/modals.py:1-85, mbbank_mcp/core.py:133-149

Connectivity and Communication Modes

The server supports two distinct communication protocols for the MCP standard:

1. Stdio Mode: The default mode where the server communicates via standard input and output, typically used when the MCP server is launched as a subprocess by a client like Claude Desktop.
2. SSE (Server-Sent Events) Mode: Enabled via the --sse flag, this mode utilizes Starlette and Uvicorn to provide an HTTP-based streaming interface.

Conclusion

The MBBank MCP server architecture prioritizes a stateless interface for monitoring while maintaining a secure, state-aware flow for sensitive operations like transfers. By abstracting the complexities of the MBBank API into standardized MCP tools and normalized Pydantic models, it enables LLMs to perform sophisticated financial analysis and transaction management within a secure environment.

Sources: mbbank_mcp/core.py:19-25, README.md:65-71