comdirect-api-wrapper

A modern, type-safe Python wrapper for the comdirect REST API.

This library allows you to interact with your Comdirect bank accounts programmatically. It handles the complex OAuth2 authentication flow (including 2FA challenge-response for PhotoTAN, PushTAN, and SMS-TAN), auto-refreshes tokens, and provides a pythonic interface for retrieving balances, transactions, and depot positions.

Includes an MCP server! Connect your AI so it can analyze your positions and judge your 💎🙌 (or lack thereof). See MCP_USAGE.md for maximum loss potential.

Warnung (in Deutsch weil Comdirect)

Leute es geht hier um euer Geld. Nutzt diese Bibliothek nur, wenn ihr den Code versteht und euch den Risiken bewusst seid.

Ich bin auch nicht perfekt, aber übernehme keine Haftung für Schäden, die durch die Nutzung dieser Software entstehen. Falls Euch was auffällt, gern PRs oder Issues.

Die API und damit das Repo hier nutzen aktuell nur lesende Endpunkte, aber Fehler können immer passieren. Comdirect kann die API ändern, Dependencies können im Zweifel auch Mist bauen (Supply-Chain Attacks) und 2FA hilft zwar, ist aber kein Freifahrtschein.

Bitte:

• Nutzt das nur lokal auf eurem eigenen Rechner.
• Teilt eure Zugangsdaten mit niemandem.
• Packt Secrets in .env und committet die Datei nie.
• Nutzt die Pre-Commit Hooks um Secrets zu scannen. Gute Zeit bissel Devops-Kram zu lernen.
• Spielt Updates nicht blind ein (Lockfile/Pinning hilft) und schaut bei Änderungen kurz drüber.

MCP-Server: Wenn ihr den Server an einen nicht-lokalen AI-Client hängt, gehen deine Daten raus. Je nach Client/Setup können Kontodaten/Transaktionen in Logs/Telemetry landen oder durch Prompt-Injection aus Dokumenten/Verwendungszwecken in komische Richtungen gehen (MCP Horror Stories: The GitHub Prompt Injection Data Heist). Nutzt MCP nur, wenn ihr der Umgebung wirklich vertraut, und gebt nur die Daten frei, die ihr dafür braucht.

Da der gemeine r/finanzen User eh schon seine Kontoauszüge in ChatGPT kopiert, könnt ihr damit machen, was ihr wollt, auf eure eigene Verantwortung!

Idealerweise ohne unnötige personenbezogene Daten. (Hauptsache, ihr lasst 'nen Stern da.)

Features

• Authentication: Full OAuth2 support with automatic token refresh and session handling.
• 2FA Support: Built-in callbacks for PhotoTAN (App), PushTAN, and SMS-TAN.
• Banking: Retrieve account lists, balances, and transaction history.
• Brokerage: Fetch depot overviews and detailed position data.
• Documents: Download postbox documents (PDFs).
• Type Safe: Fully typed domain models for great IDE support and autocompletion.

Installation

Using uv (Recommended)

uv add comdirect-api-wrapper

Using pip

pip install comdirect-api-wrapper

Quick Start

1. Prerequisites

You need user credentials AND API credentials from Comdirect.

1. Enable API access in your Comdirect settings (https://www.comdirect.de/cms/kontakt-zugaenge-api.html).
2. Obtain your client_id and client_secret.
3. Your smartphone with the Comdirect PhotoTAN app installed (for 2FA).

2. Configuration

python-dotenv to manage secrets. Create a .env file:

COMDIRECT_USERNAME=your_username
COMDIRECT_PASSWORD=your_password
COMDIRECT_CLIENT_ID=your_client_id
COMDIRECT_CLIENT_SECRET=your_client_secret

3. Usage Example

import os
from dotenv import load_dotenv
from comdirect_api.client import ComdirectClient
from comdirect_api.utils import default_photo_tan_callback, default_push_tan_callback

load_dotenv()

# 1. Setup Credentials
credentials = {
    "username": os.getenv("COMDIRECT_USERNAME"),
    "password": os.getenv("COMDIRECT_PASSWORD"),
    "client_id": os.getenv("COMDIRECT_CLIENT_ID"),
    "client_secret": os.getenv("COMDIRECT_CLIENT_SECRET"),
}

# 2. Setup 2FA Handlers (What happens when the bank asks for a TAN?)
tan_handlers = {
    # For PhotoTAN App (Push):
    "push_tan_cb": default_push_tan_callback,
    # For PhotoTAN Graphic (Scan):
    "photo_tan_cb": default_photo_tan_callback,
}

# 3. Initialize & Login
client = ComdirectClient(credentials, tan_handlers)
client.login() # Triggers 2FA interaction if needed

# 4. Fetch Data
# --- Accounts ---
for account in client.list_accounts():
    print(f"Account: {account.id} | Balance: {account.balance} {account.currency}")

    # Fetch Transactions
    for tx in client.list_transactions(account.id):
        print(f"  {tx.booking_date}: {tx.amount} {tx.currency} - {tx.purpose}")

    # # or
    # transactions = list(client.iter_all_transactions(account.id))
    # for tx in transactions:
    #     print(f"  {tx.booking_date}: {tx.amount} {tx.currency} - {tx.purpose}")

# --- Depot ---
for depot in client.list_depots():
    balance, positions = client.get_depot_positions(depot.id)
    print(f"Depot Value: {balance.current_value} EUR")
    for pos in positions:
        print(f"  {pos.quantity}x {pos.instrument_name} ({pos.wkn})")

Advanced Usage

Pagination

For accounts with many transactions, use the iterator which handles pagination automatically:

for tx in client.iter_all_transactions(account_id):
    # This automatically fetches pages as you iterate
    process_transaction(tx)

Document Retrieval

docs = client.list_documents()
for doc in docs:
    print(f"Downloading {doc.name}...")
    pdf_bytes = client.download_document(doc.id, doc.mime_type)
    with open(f"{doc.name}.pdf", "wb") as f:
        f.write(pdf_bytes)

Model Context Protocol (MCP) Server

This library includes a fully functional Model Context Protocol (MCP) server. This allows AI assistants (like Claude Desktop) to connect directly to your Comdirect accounts to fetch balances, search transactions, and analyze your portfolio.

See MCP_USAGE.md for setup and usage instructions.

Quick Config for Claude Desktop

{
  "mcpServers": {
    "comdirect": {
      "command": "python",
      "args": ["/absolute/path/to/comdirect-api-wrapper/mcp_server.py"],
      "env": {
        "COMDIRECT_CLIENT_ID": "...",
        "COMDIRECT_CLIENT_SECRET": "...",
        "COMDIRECT_USERNAME": "...",
        "COMDIRECT_PASSWORD": "..."
      }
    }
  }
}

Disclaimer

This project is not affiliated with, maintained, or endorsed by the comdirect bank. Use this software at your own risk. I provide no warranty and accept no liability for any financial losses or damages resulting from the use of this software.

This project is designed to run locally and does not collect, store, or transmit your banking credentials to any third parties.

Nevertheless, be cautious and review the code before use, especially when dealing with sensitive financial data.

License: MIT

Development

Pre-commit Hooks

This project uses pre-commit to ensure code quality and prevent accidental secret commits.

1. Install pre-commit:

   uv pip install pre-commit
   

2. Install the git hooks:

   pre-commit install
   

Now, checks (formatting, linting, secret scanning) will run automatically before every commit.