Quickstart Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• mbbank_mcp/core.py
• mbbank_mcp/main.py
• mbbank_mcp/modals.py
• mbbank_mcp/init.py

This guide provides the necessary technical information to install, configure, and operate the MBBank MCP (Model Context Protocol) server. The server acts as a bridge between the MBBank API and MCP-compatible clients (like Claude Desktop), enabling secure monitoring of balances, transaction history, and card management.

The project is built using Python 3.10+ and utilizes mbbank-lib for core banking interactions, while implementing the mcp SDK to expose these functionalities as tools for LLMs.

Sources: README.md:1-10, pyproject.toml:5-15, mbbank_mcp/core.py:10-25

Prerequisites

Before deployment, ensure the following requirements are met:

• Python Runtime: Version 3.10 or higher.
• Package Manager: uv is recommended for installation and execution.
• MBBank Credentials: Valid username and password for the MBBank mobile/online banking application.
• Dependencies: The system relies on mcp, mbbank-lib, qrcode, and uvicorn.

Sources: README.md:5-7, pyproject.toml:7-22

Installation and Configuration

Claude Desktop Integration

To use the MBBank MCP server with Claude Desktop, modify your configuration file to include the mbbank server definition.

{
    "mcpServers": {
        "mbbank": {
            "command": "uvx",
            "args": [
                "mbbank-mcp",
                "--username=<your_username>",
                "--password=<your_password>"
            ]
        }
    }
}

Sources: README.md:14-29

Docker Deployment

Alternatively, the server can be run as a Docker container, passing credentials through environment variables.

docker run -i --rm \
  -e MBBANK_USERNAME="your_user" \
  -e MBBANK_PASSWORD="your_password" \
  thedtvn/mbbank-mcp:latest

Sources: README.md:31-50

Server Operation Modes

The MBBank MCP server supports two primary communication modes: Stdio and SSE (Server-Sent Events).

Stdio Mode (Default)

Used primarily when the server is launched as a subprocess by a client like Claude Desktop. It communicates via standard input/output.
Sources: mbbank_mcp/main.py:75-77

SSE Mode

Enables the server to run as a standalone web service using uvicorn and starlette. This mode supports streamable HTTP connections.

uvx mbbank-mcp --username=<user> --password=<pass> --host=localhost --port=3000 --sse

Sources: README.md:52-60, mbbank_mcp/main.py:47-73

The following diagram illustrates the initialization flow of the server:

This diagram shows the startup logic and authentication check before the server enters its listening loop.
Sources: mbbank_mcp/main.py:29-77

Available Tools and Features

The server exposes several tools that provide access to MBBank data. These tools return structured data defined in modals.py.

Core Tools Table

Tool Name	Purpose	Key Parameters
get_balances	Returns balances for all accounts.	None
get_transactions	Fetches transaction history for a specific account.	account_number, from_date, to_date
get_cards	Lists all credit/debit cards and their statuses.	None
get_savings	Lists online and branch savings accounts.	None
start_transfer	Initiates a transfer and generates a confirmation QR.	from_account, to_account, amount, bank_code
verify_transfer	Finalizes a transfer using a session ID and OTP.	sid, otp

Sources: mbbank_mcp/core.py:112-255

Transfer Process Flow

The transfer system is designed for security, requiring manual OTP verification via the MBBank app's D-OTP feature.

This sequence diagram details the two-step transfer process involving QR code generation and OTP verification.
Sources: mbbank_mcp/core.py:34-100

Configuration Options

Option	Argument	Environment Variable	Default
Username	--username	MBBANK_USERNAME	None (Required)
Password	--password	MBBANK_PASSWORD	None (Required)
Port	--port	N/A	3000
Host	--host	N/A	localhost
Mode	--sse	N/A	stdio (if flag absent)

Sources: README.md:54-60, mbbank_mcp/main.py:23-34

Security Considerations

The MBBank MCP server is designed for monitoring and analytics. While it supports initiating transfers, it cannot bypass the bank's security measures:

1. D-OTP: Transfers require a QR code scan and OTP generation within the official MBBank mobile app.
2. Session Expiration: Transfer sessions (identified by sid) expire automatically after 120 seconds.
3. Data Sensitivity: Users are warned that the server accesses sensitive balance and transaction data and should only be deployed in trusted environments.

Sources: README.md:73-82, mbbank_mcp/core.py:80-90

This Quickstart Guide provides the foundation for integrating MBBank data into MCP clients, ensuring developers can quickly set up the server while maintaining awareness of the underlying security protocols and operational modes.