MBBank Data Fetching
Relevant source files
The following files were used as context for generating this wiki page:
MBBank Data Fetching is a core component of the mbbank-mcp project, designed to interface with MBBank's internal systems via the mbbank-lib library. Its primary purpose is to provide an Model Context Protocol (MCP) interface for monitoring and analytics, allowing users or automated systems to retrieve account balances, transaction histories, card details, and savings information.
The system acts as a secure read-only proxy (with the exception of transfer initiation) that translates raw bank API responses into structured, developer-friendly Pydantic models. It supports both standard input/output (stdio) and Server-Sent Events (SSE) communication modes for integration with various MCP clients like Claude Desktop.
Sources: README.md:1-10, mbbank_mcp/core.py:10-30, pyproject.toml:10-20
Architecture and Data Flow
The data fetching architecture follows a layered approach where the MCP server defines tools that call asynchronous methods from the MBBankAsync client. Data retrieved from the bank is passed through a transformation layer that maps raw API response objects into cleaned models defined in modals.py.
System Overview Diagram
This diagram illustrates the flow from a client request through the MCP server to the MBBank backend.
Core Data Models
The system uses Pydantic models to ensure type safety and provide a consistent schema for different types of financial data. These models act as a proxy to rename internal bank fields to more descriptive names.
Primary Data Structures
| Model | Purpose | Key Fields |
|---|---|---|
AccountModel | Represents a single bank account. | accountNumber, accountName, balance, currency |
TransactionModel | Individual transaction record. | transactionDate, amount, description, transferredTo |
CardModel | Details of credit/debit cards. | cardId, cardNumber, cardStatus, cardType |
SavingModel | Information on fixed deposits or online savings. | principalAmount, maturityDate, ratePercentPerYear |
Sources: mbbank_mcp/modals.py:1-75
Data Fetching Operations
The system provides several specialized tools for retrieving different types of financial information.
Account and Balance Retrieval
The get_balances tool fetches information for both standard and international accounts. It aggregates data into a BalancesModel.
Sources: mbbank_mcp/core.py:126-146
Transaction History
Transaction fetching is available for both bank accounts and cards. These operations require date ranges in dd-mm-yyyy format.
- Account Transactions: Uses
getTransactionAccountHistory. It identifies if an amount is a credit (positive) or debit (negative) based on the presence ofcreditAmountordebitAmount. - Card Transactions: Uses
getCardTransactionHistoryto retrieve card-specific spending logs.
Sources: mbbank_mcp/core.py:155-185, mbbank_mcp/core.py:207-228
Savings and Interest Rates
The system supports fetching details for two types of savings:
- OSA: Online Savings Accounts.
- SBA: Saving Bank Accounts (Branch-based).
The get_interest_rates tool allows querying current rates for VND, USD, or EUR.
Sources: mbbank_mcp/core.py:231-285, mbbank_mcp/modals.py:77-104
Authentication and Security
Data fetching requires a valid session initiated via the MBBankAsync client. The server performs an initial authentication check during startup.
- Authentication: The
mainfunction ensuresMBBANK_USERNAMEandMBBANK_PASSWORDare present before starting the server and runs_authenticate()to verify credentials. - Safety Constraints: The server is explicitly designed for monitoring and analytics. While it includes a
start_transfertool, it requires manual user intervention via QR code scanning and OTP verification, and cannot perform withdrawals autonomously.
Sources: mbbank_mcp/main.py:31-45, README.md:65-75
Technical Implementation Details
The implementation leverages FastMCP for tool definition and uvicorn for SSE hosting.
# mbbank_mcp/core.py:148-153
@fast_mcp.tool()
async def get_today_date() -> str:
"""
Get today's date in the format dd-mm-yyyy used for MB Bank transactions.
"""
today = datetime.datetime.now()
return today.strftime("%d-%m-%Y")
The system also includes a get_bank_list helper to facilitate transfers by providing valid bankCode values required by the MBBank API.
Sources: mbbank_mcp/core.py:120-124, mbbank_mcp/main.py:47-65
Summary
The MBBank Data Fetching module provides a robust, asynchronous interface for accessing MBBank financial data through the Model Context Protocol. By utilizing Pydantic models for data normalization and supporting multiple transport modes (Stdio/SSE), it enables seamless integration with AI assistants and analytics tools while maintaining strict security boundaries for sensitive financial operations.