Claude Desktop Integration

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

The Claude Desktop Integration allows users to connect their MBBank accounts to the Claude Desktop application using the Model Context Protocol (MCP). This integration facilitates real-time monitoring, transaction analysis, and balance checking directly within the Claude interface by leveraging the mbbank-lib as the core communication layer with MBBank's infrastructure.

Sources: README.md:1-5, pyproject.toml:3-17

Installation and Configuration

Integration with Claude Desktop is achieved by modifying the Claude Desktop configuration file to include the mbbank-mcp server. The server can be run either via uvx for local execution or through Docker for containerized environments.

Local Configuration (uvx)

For users with Python and uv installed, the following JSON configuration is added to the Claude Desktop mcpServers section:

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

Sources: README.md:15-30

Docker Configuration

Alternatively, the server can be deployed via Docker, passing credentials through environment variables to ensure compatibility with the Python runtime within the container.

{
    "mcpServers": {
        "mbbank": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "MBBANK_USERNAME",
                "-e",
                "MBBANK_PASSWORD",
                "thedtvn/mbbank-mcp:latest"
            ],
            "env": {
                "MBBANK_USERNAME": "<your_username>",
                "MBBANK_PASSWORD": "<your_password>"
            }
        }
    }
}

Sources: README.md:32-53

Architecture and Data Flow

The integration operates as a bridge between Claude Desktop (acting as the MCP Client) and the MBBank API. The mbbank-mcp server utilizes FastMCP to define tools that Claude can invoke.

Communication Flow

When Claude Desktop starts the server, it initiates a bidirectional communication channel, typically via stdio. The server authenticates with MBBank using the provided credentials upon startup.

The diagram shows the request flow from the Claude Desktop UI through the MCP server logic to the external MBBank API.
Sources: mbbank_mcp/core.py:24-30, mbbank_mcp/main.py:30-41

Key Features and Tools

The integration exposes several tools to Claude Desktop, enabling comprehensive account management.

Tool Catalog

Tool Name	Purpose	Key Parameters
get_balances	Retrieves current balances for all accounts.	None
get_transactions	Fetches history for a specific account.	account_number, from_date, to_date
get_cards	Lists all associated debit/credit cards.	None
get_savings	Displays online and branch savings accounts.	None
start_transfer	Initiates a transfer and generates a confirmation QR.	from_account, to_account, amount, message
verify_transfer	Completes a transfer using a 2FA OTP.	sid, otp

Sources: mbbank_mcp/core.py:110-230

Secure Transfer Workflow

The transfer process is a two-step "scan-and-verify" flow designed for security. It involves generating a QR code that the user must scan with their physical MBBank app to receive an OTP.

This sequence illustrates the interaction between the user, Claude, and the banking backend during a sensitive transaction.
Sources: mbbank_mcp/core.py:32-101

Implementation Details

Data Modeling

The integration uses Pydantic models in modals.py to sanitize and rename raw API responses into developer-friendly structures. This ensures that Claude receives clean, structured data for better reasoning.

• Balances: BalancesModel contains lists of AccountModel objects for standard and international accounts.
• Transactions: TransactionsModel wraps TransactionModel, which includes optional transferredTo details for outgoing payments.
• Savings: SavingsModel distinguishes between Online Savings (OSA) and Branch Savings (SBA).

Sources: mbbank_mcp/modals.py:1-100

Technical Requirements

The server is built on Python 3.10+ and requires several core dependencies defined in pyproject.toml:

• mcp: The underlying protocol implementation.
• mbbank-lib: The unofficial MBBank API wrapper.
• qrcode[pil]: Used to generate the transfer confirmation images.
• starlette / uvicorn: Used when running in SSE (Server-Sent Events) mode.

Sources: pyproject.toml:7-21

Conclusion

Claude Desktop Integration provides a secure, tool-based interface for MBBank users to interact with their financial data through an AI assistant. By implementing the Model Context Protocol, the project enables Claude to perform complex tasks like transaction history analysis and balance monitoring while maintaining security through two-step verification for sensitive operations like transfers.