Transaction Analytics Feature
Relevant source files
The following files were used as context for generating this wiki page:
The Transaction Analytics Feature within the mbbank-mcp project provides a Model Context Protocol (MCP) interface for monitoring and analyzing MBBank financial data. Its primary purpose is to allow language models or automated tools to retrieve account balances, transaction histories, and card-specific financial activities securely and efficiently.
The system acts as a middleware between the MBBank API (via the mbbank-lib library) and MCP clients like Claude Desktop. It focuses strictly on read-only monitoring and analytical operations to ensure user security, although it includes a controlled workflow for initiating transfers that requires external manual authorization.
Sources: README.md:3-5, README.md:73-80, pyproject.toml:5-18
Core Architecture and Data Flow
The feature is built on the FastMCP framework, which exposes Python functions as tools to be consumed by MCP-compatible clients. The server can run in two modes: Standard Input/Output (stdio) for local integration or Server-Sent Events (SSE) for HTTP-based communication.
System Components
The diagram shows the data flow from the user client through the MCP server tools to the MBBank backend.
Sources: mbbank_mcp/core.py:18-24, mbbank_mcp/main.py:47-75, README.md:14-45
Transaction Retrieval and Monitoring
The system provides specialized tools to fetch and normalize transaction data from various sources, including standard bank accounts and payment cards.
Account Transactions
The get_transactions tool fetches historical data for a specific account. It requires a date range in dd-mm-yyyy format and returns a structured TransactionsModel.
| Parameter | Type | Description |
|---|---|---|
account_nuber | str | The target MBBank account number |
from_date | str | Start date (dd-mm-yyyy) |
to_date | str | End date (dd-mm-yyyy) |
Sources: mbbank_mcp/core.py:126-155, mbbank_mcp/modals.py:27-32
Card Analytics
For credit or debit cards, the get_card_transactions tool provides similar historical insights. It uses a card_id obtained from the get_cards tool to query the bank's backend.
The sequence illustrates the transformation of raw API data into normalized models.
Sources: mbbank_mcp/core.py:178-200, mbbank_mcp/modals.py:34-47
Balance and Account Management
The analytics feature relies on accurate account discovery and balance tracking. The get_balances tool aggregates data from both domestic and international accounts.
Data Normalization
The server uses modals.py to rename and structure raw API fields into developer-friendly formats. For example, AccountModel standardizes account details:
| Field | Type | Description |
|---|---|---|
accountNumber | str | Unique identifier for the account |
accountName | str | Alias or holder name |
currency | str | Currency code (e.g., VND, USD) |
balance | str | Current available balance |
Sources: mbbank_mcp/modals.py:5-15, mbbank_mcp/core.py:105-120
Savings and Interest Analytics
A specialized module handles the analysis of savings accounts, including Online Savings (OSA) and Branch Savings (SBA).
Savings Detailed Analysis
The get_saving_details tool provides deep insights into specific savings contracts, including maturity dates and accrued interest.
The diagram represents the relationship between high-level saving summaries and granular detail models.
Sources: mbbank_mcp/core.py:228-270, mbbank_mcp/modals.py:49-85
Implementation Details
Server Entry Point
The application is initialized via mbbank_mcp/__main__.py. It handles authentication with the MBBank API before starting the MCP server.
# mbbank_mcp/__main__.py:36-42
mbbank_client = MBBankAsync(
username=username,
password=password
)
mcp_server = crate_mcp_server(mbbank_client, port=port)
asyncio.run(mbbank_client._authenticate())
Sources: mbbank_mcp/main.py:36-43
Transfer Authorization Workflow
While primarily for analytics, the system supports a two-step transfer process (start_transfer and verify_transfer) that generates a QR code for manual D-OTP confirmation in the official MBBank app.
Sources: mbbank_mcp/core.py:26-94
Summary
The Transaction Analytics Feature of mbbank-mcp provides a robust, schema-driven way to access MBBank financial data. By utilizing FastMCP and structured Pydantic models in modals.py, it ensures that financial information is presented in a consistent format across different account and transaction types. The system's design prioritizes read-only analytics while maintaining a secure, QR-based path for authorized transactions.