Comdirect MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to comdirect banking and brokerage operations.

Quick Start

Use directly with npx (no installation needed):

npx @teonla/comdirect-mcp@latest

Setup

Add to your MCP client configuration:

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "comdirect": {
      "command": "npx",
      "args": ["-y", "@teonla/comdirect-mcp@latest"],
      "env": {
        "COMDIRECT_CLIENT_ID": "your_client_id",
        "COMDIRECT_CLIENT_SECRET": "your_client_secret",
        "COMDIRECT_USERNAME": "your_username",
        "COMDIRECT_PASSWORD": "your_password"
      }
    }
  }
}

Bob (VS Code)

Create .bob/mcp.json in your workspace:

{
  "mcpServers": {
    "comdirect": {
      "command": "npx",
      "args": ["-y", "@teonla/comdirect-mcp@latest"],
      "env": {
        "COMDIRECT_CLIENT_ID": "your_client_id",
        "COMDIRECT_CLIENT_SECRET": "your_client_secret",
        "COMDIRECT_USERNAME": "your_username",
        "COMDIRECT_PASSWORD": "your_password"
      }
    }
  }
}

Continue.dev

Edit ~/.continue/config.json:

{
  "mcpServers": {
    "comdirect": {
      "command": "npx",
      "args": ["-y", "@teonla/comdirect-mcp@latest"],
      "env": {
        "COMDIRECT_CLIENT_ID": "your_client_id",
        "COMDIRECT_CLIENT_SECRET": "your_client_secret",
        "COMDIRECT_USERNAME": "your_username",
        "COMDIRECT_PASSWORD": "your_password"
      }
    }
  }
}

Usage

Authentication (Required First!)

Before using any banking or brokerage tools, you must authenticate:

You: "Authenticate with comdirect"
AI: "📱 Push notification sent to your device. Please approve..."
You: [Approve on your phone]
AI: "✅ Authentication successful!"

That's it! The server uses pushTAN - just approve on your device, no codes to type!

Example Conversation

You: "Check my comdirect account balances"
AI: "You need to authenticate first."
You: "Authenticate with comdirect"
AI: "📱 Push notification sent..."
You: [Approve on phone]
AI: "✅ Authenticated! Here are your balances:
     - Girokonto: €1,234.56
     - Tagesgeld: €5,678.90"

You: "Show my depot positions"
AI: "Here are your positions:
     - Apple Inc. (AAPL): 10 shares @ $150.00
     - Microsoft Corp. (MSFT): 5 shares @ $380.00"

Available Tools

The server provides 18 MCP tools:

Authentication

Single-Step (Recommended):

• authenticate - Complete authentication flow (all 5 steps at once)
• get_session_status - Check authentication status

Step-by-Step (For Testing/Debugging):

• authenticate_primary - Step 1: Primary OAuth2 authentication
• create_session - Step 2: Create session
• request_tan_challenge - Step 3: Request TAN challenge
• activate_tan - Step 4: Activate TAN (pushTAN or manual)
• authenticate_secondary - Step 5: Secondary OAuth2 authentication

💡 Tip: Use the single-step authenticate tool for normal operations. Use the step-by-step tools when you need more control or want to debug authentication issues. See AUTHENTICATION_WORKFLOW.md for details.

Banking

• get_account_balances - Get balances for all accounts
• get_account_transactions - Get transaction history
• get_all_balances - Get consolidated balance report

Brokerage

• get_depots - List all depots
• get_depot_positions - Get positions for a depot
• get_orders - View orders for a depot
• get_quotes - Get quotes for an instrument
• get_instrument - Get instrument details
• validate_order - Validate an order before creation
• create_order - Create a new order (requires TAN)

Documents

• get_documents - Access account documents and messages

Configuration

Required Environment Variables

• COMDIRECT_CLIENT_ID - Your comdirect API client ID
• COMDIRECT_CLIENT_SECRET - Your comdirect API client secret
• COMDIRECT_USERNAME - Your comdirect username (Zugangsnummer)
• COMDIRECT_PASSWORD - Your comdirect password (PIN)

Optional Environment Variables

• COMDIRECT_API_BASE_URL - API base URL (default: https://api.comdirect.de)
• COMDIRECT_RATE_LIMIT_PER_SECOND - Max requests per second (default: 10)
• COMDIRECT_RATE_LIMIT_PER_MINUTE - Max requests per minute (default: 100)
• COMDIRECT_REQUEST_TIMEOUT - HTTP request timeout in seconds (default: 30)
• COMDIRECT_MAX_RETRIES - Maximum retry attempts (default: 3)
• COMDIRECT_LOG_LEVEL - Logging level (default: INFO)

Security

⚠️ Important:

• Never commit credentials to version control
• Use environment variables for credentials
• TAN codes are never logged or stored
• Tokens are stored in memory only
• All API communication uses HTTPS

Troubleshooting

Authentication Issues

Problem: "Invalid credentials" error
Solution: Verify your COMDIRECT_CLIENT_ID and COMDIRECT_CLIENT_SECRET

Problem: pushTAN timeout
Solution: Approve the push notification within 60 seconds

Problem: "No secondary token" error
Solution: Run the authenticate tool first

Rate Limiting

Problem: "Rate limit exceeded" errors
Solution: The server automatically backs off. Wait a few seconds and retry.

Connection Issues

Problem: Timeout errors
Solution: Check your internet connection or increase COMDIRECT_REQUEST_TIMEOUT

Support

• GitHub Issues: https://github.com/teonla/comdirect-mcp/issues
• NPM Package: https://www.npmjs.com/package/@teonla/comdirect-mcp

License

MIT License - see LICENSE file for details