Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The MBBank MCP Server is a specialized Model Context Protocol (MCP) implementation designed to interface with the MBBank API. Its primary purpose is to facilitate the monitoring and analytics of bank transactions, balances, and savings accounts through a standardized protocol. Built using the mbbank-lib and the FastMCP framework, it acts as a bridge between LLM-based applications (like Claude Desktop) and MBBank's digital services.
Sources: README.md:1-5, pyproject.toml:1-15, mbbank_mcp/core.py:18-22
The system is designed for read-only monitoring and analytics by default, although it includes tools for initiating and verifying transfers. It prioritizes security by using session-based transfer management and strictly adhering to authentication protocols required by the underlying bank library.
Sources: README.md:74-85, mbbank_mcp/core.py:27-105
System Architecture
The project follows a modular structure where the core logic is encapsulated in a server factory, while data structures are managed through Pydantic models. The server can operate in two distinct communication modes: Standard Input/Output (stdio) or Server-Sent Events (SSE).
Component Overview
| Component | Responsibility |
|---|---|
__main__.py | Handles CLI arguments, environment variables, and server lifecycle. |
core.py | Defines the MCP tools and integrates the MBBankAsync client. |
modals.py | Contains Pydantic models for data normalization and API responses. |
mbbank-lib | External dependency providing the low-level API communication with MBBank. |
Sources: mbbank_mcp/main.py:31-77, mbbank_mcp/core.py:27-241, mbbank_mcp/modals.py:1-105, pyproject.toml:15-23
High-Level Data Flow
The following diagram illustrates the interaction between a user (via an MCP client), the MCP server, and the MBBank backend.
Core Features and Tools
The server exposes several tools that allow an LLM to interact with the bank account. These tools are registered using the @fast_mcp.tool() decorator within the crate_mcp_server function.
Account and Transaction Management
The server provides tools to retrieve balances and transaction histories for both standard accounts and cards. Data is mapped from the raw library responses into internal models like BalancesModel and TransactionsModel.
| Tool Name | Description | Key Parameters |
|---|---|---|
get_balances | Retrieves current balances for all accounts. | N/A |
get_transactions | Fetches transaction history for a specific account. | account_nuber, from_date, to_date |
get_cards | Lists all cards associated with the user. | N/A |
get_card_transactions | Fetches history for a specific card ID. | card_id, from_date, to_date |
Sources: mbbank_mcp/core.py:116-193, mbbank_mcp/modals.py:6-55
Savings and Interest Rates
The server includes specialized logic for handling Online Savings Accounts (OSA) and Branch Saving Accounts (SBA), including detailed views and interest rate lookups.
Sources: mbbank_mcp/core.py:195-239, mbbank_mcp/modals.py:75-105
Transfer Workflow
The transfer system is a two-step process requiring manual user confirmation via a QR code and OTP. This flow ensures that while the LLM can initiate the process, the final authorization remains with the user.
Sources: mbbank_mcp/core.py:32-105
Security and Expiration
Transfer sessions are tracked in a transfer_manager dictionary. Each session is assigned a unique 8-character hex Session ID (SID). To prevent memory leaks and orphaned requests, a background task _remove_expired_transfers runs to delete sessions older than 120 seconds.
Sources: mbbank_mcp/core.py:30-31, mbbank_mcp/core.py:72-83
Technical Implementation Details
Configuration and Deployment
The server can be configured via command-line options or environment variables.
| Option | Environment Variable | Default | Description |
|---|---|---|---|
--username | MBBANK_USERNAME | None | MBBank Login ID |
--password | MBBANK_PASSWORD | None | MBBank Password |
--host | N/A | localhost | SSE Server Host |
--port | N/A | 3000 | SSE Server Port |
--sse | N/A | False | Toggle between Stdio and SSE |
Sources: mbbank_mcp/main.py:24-30, README.md:60-68
Server Modes
The application supports two primary execution modes in main():
- Stdio Mode: The default mode where the server communicates over standard input/output. It is suitable for local integrations like Claude Desktop.
- SSE Mode: Uses
uvicornandStarletteto host a web server that supports Server-Sent Events and streamable HTTP.
Sources: mbbank_mcp/main.py:49-77
Versioning and Dependencies
The project is managed using setuptools and uv.
- Python Requirement:
>=3.10 - Core Dependencies:
mcp,mbbank-lib,uvicorn,starlette,qrcode[pil],pillow. - Version: Current version is defined as
0.0.7.
Sources: pyproject.toml:5-23, mbbank_mcp/init.py:3
Summary
The MBBank MCP Server provides a robust, tool-based interface for managing MBBank accounts through the Model Context Protocol. By abstracting the complexities of the bank's API and providing structured data models, it enables AI agents to perform detailed financial monitoring and initiate secure, user-verified transfers. The architecture supports flexible deployment through both local stdio and network-based SSE protocols, ensuring compatibility with various MCP client environments.