# traderepublic-mcp

A **read-only** [MCP](https://modelcontextprotocol.io) server for [Trade Republic](https://traderepublic.com), built on [pytr](https://github.com/pytr-org/pytr).

Designed as the data backend for the [ethical-invest-advisor](https://github.com/tommasolovergine/ethical-invest-advisor) Claude Cowork plugin, but usable from any MCP client.

## Read-only by design

This server intentionally exposes **no** tool that can place, modify or cancel orders, savings plans, or payouts — even though pytr supports some of these. Analysis in, decisions out: any actual operation is done by the human in the Trade Republic app. Forks that add execution tools operate real money over an unofficial API; think twice.

## ⚠️ Unofficial API

Trade Republic has no public API. pytr reverse-engineers the private WebSocket API used by the web app. Using it may violate Trade Republic's Terms of Service, and the API can change without notice. Not affiliated with Trade Republic Bank GmbH. Use at your own risk.

## Tools

| Tool | Description |
| --- | --- |
| `tr_status` | Authentication status |
| `tr_login` | Log in (resumes saved session when possible, no 2FA needed) |
| `tr_verify_2fa` | Complete login with the 4-digit code from the TR app |
| `get_portfolio` | Positions with quantity, average cost, value, names |
| `get_cash_balance` | Available cash |
| `get_portfolio_history` | Aggregated portfolio value over time |
| `get_ticker` | Real-time quote by ISIN |
| `get_instrument_details` | Instrument info by ISIN |
| `get_performance_history` | Price history by ISIN |
| `search_instruments` | Search stocks, funds, bonds, crypto |

## Install

Requires Python 3.10+.

```bash
uv tool install git+https://github.com/tommasolovergine/traderepublic-mcp-py
# or: pipx install git+https://github.com/tommasolovergine/traderepublic-mcp-py
```

This puts a `traderepublic-mcp` executable on your PATH (stdio transport). If your MCP client is a GUI app that doesn't inherit your shell PATH, reference the executable by absolute path in its configuration (e.g. `~/.local/bin/traderepublic-mcp`).

Login needs an AWS WAF anti-bot token. The server first tries a pure-Python solver; if that fails it falls back to a headless Chromium via Playwright, which needs a one-time setup:

```bash
playwright install chromium
```

## MCP client configuration

```json
{
  "mcpServers": {
    "trade-republic": {
      "command": "traderepublic-mcp"
    }
  }
}
```

## Authentication and credential handling

- Login mirrors the TR web app: phone + PIN, then a 4-digit code shown in your Trade Republic app.
- The session cookie is stored by pytr in `~/.pytr/cookies.txt` and resumed automatically — 2FA is only needed when the session expires.
- This server never writes your phone/PIN to disk. Only if you explicitly call `tr_login` with `store_credentials=true` will pytr store them (plaintext, `~/.pytr/credentials`) — convenient but not recommended.
- Never commit anything from `~/.pytr/` anywhere.

## Development

```bash
git clone https://github.com/tommasolovergine/traderepublic-mcp-py
cd traderepublic-mcp-py
uv sync  # or: pip install -e .
```

## License

MIT