# trading212-mcp

MCP server for the [Trading 212 public API](https://docs.trading212.com/) —
equities and ETF investing on Invest and Stocks ISA accounts. It exposes the
account, portfolio, order, pie, and history endpoints as MCP tools, defaults
to the demo (paper trading) environment, and keeps trading tools hidden
unless explicitly enabled.

## Features

- Read coverage of the whole public API: account summary, instrument
  universe, exchange schedules, open positions, pending orders, pies,
  historical orders, dividends, cash transactions, and CSV exports.
- Trading tools (order placement/cancellation, pie management, export
  requests) are opt-in via an environment flag and stay invisible to the
  MCP client otherwise.
- Demo environment by default; live is an explicit choice.
- Responses are trimmed to the fields a trader acts on, and list tools
  accept a `limit` parameter to keep payloads small.
- One automatic retry on HTTP 429, honouring the `Retry-After` header
  capped at 30 seconds (Trading 212 rate limits are strict and
  per-endpoint).
- stdio transport by default, HTTP (`/mcp`) on request.

## Tools

Read tools (always registered):

| Tool | Description |
|---|---|
| `get_account_summary` | Account summary: cash breakdown, investments, and overall result |
| `list_exchanges` | Exchanges with working schedules trimmed to session open/close events |
| `list_instruments` | Search the tradable instrument universe by ticker/name substring and type |
| `get_portfolio` | List all open positions with quantity, prices, and unrealized P/L |
| `get_position` | Fetch a single open position by its Trading 212 ticker |
| `list_orders` | List all pending equity orders |
| `get_order` | Fetch one pending equity order by its id |
| `list_pies` | List all pies with money-in, progress, and performance |
| `get_pie` | Fetch one pie's full definition and per-instrument breakdown |
| `list_historical_orders` | List executed equity orders, newest first (cursor-paginated) |
| `list_dividends` | List paid-out dividends (cursor-paginated) |
| `list_transactions` | List cash transactions: deposits, withdrawals, fees, transfers (cursor-paginated) |
| `list_exports` | List requested CSV export reports and their processing status |

Write tools (registered only when `T212_MCP_ENABLE_TRADING` is truthy):

| Tool | Description |
|---|---|
| `place_market_order` | Place a market order (positive quantity = BUY, negative = SELL) |
| `place_limit_order` | Place a limit order with a limit price and DAY/GTC validity |
| `place_stop_order` | Place a stop order that triggers a market order at the stop price |
| `place_stop_limit_order` | Place a stop-limit order (limit order placed once the stop triggers) |
| `cancel_order` | Cancel a pending equity order by its id |
| `create_pie` | Create a new pie from a ticker-to-weight allocation map |
| `update_pie` | Replace an existing pie's definition (name and full allocation) |
| `delete_pie` | Delete a pie by ID (irreversible) |
| `duplicate_pie` | Duplicate an existing pie under a new name |
| `request_export` | Request an asynchronous CSV export report of account history |

## Configuration

All configuration is via environment variables — never commit credentials.

| Variable | Default | Purpose |
|---|---|---|
| `T212_API_KEY` | — (required) | API key (Basic auth username), generated in the Trading 212 app |
| `T212_API_SECRET` | — (required) | API secret (Basic auth password) |
| `T212_ENV` | `demo` | Target environment: `demo` (paper trading) or `live` (real money) |
| `T212_MCP_ENABLE_TRADING` | off | Set to `true`/`1`/`yes`/`on` to register the write tools |

## Getting started

Run straight from the repository with [uv](https://docs.astral.sh/uv/):

```bash
uvx --from git+https://github.com/florinel-chis/trading212-mcp trading212-mcp
```

The server speaks stdio by default; add `--transport http --port 8000` to
serve MCP over HTTP at `/mcp` instead. HTTP binds `127.0.0.1` by default,
and a non-loopback `--host` is refused unless `--allow-remote` is also
passed — read the [Safety](#safety) section before using that flag.

## MCP client configuration

Add the server to your MCP client's configuration (stdio, via `uvx`):

```json
{
  "mcpServers": {
    "trading212": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/florinel-chis/trading212-mcp", "trading212-mcp"],
      "env": {
        "T212_API_KEY": "your-api-key",
        "T212_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

Or run the Docker image (build it first, see below):

```json
{
  "mcpServers": {
    "trading212": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "T212_API_KEY",
        "-e", "T212_API_SECRET",
        "trading212-mcp"
      ],
      "env": {
        "T212_API_KEY": "your-api-key",
        "T212_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

## Docker

```bash
docker build -t trading212-mcp .

# stdio (what MCP clients spawn)
docker run -i --rm -e T212_API_KEY -e T212_API_SECRET trading212-mcp

# HTTP at http://127.0.0.1:8000/mcp — publish the port on loopback only:
# the MCP endpoint is unauthenticated (see Safety)
docker run --rm -p 127.0.0.1:8000:8000 -e T212_API_KEY -e T212_API_SECRET \
  trading212-mcp --transport http --host 0.0.0.0 --port 8000 --allow-remote
```

(`--host 0.0.0.0` binds inside the container so the port mapping works —
which is why `--allow-remote` is needed; the `127.0.0.1:` prefix on `-p`
keeps the endpoint reachable from this machine only.)

## Safety

- The HTTP transport has **no authentication**: anyone who can reach the
  `/mcp` endpoint can call every registered tool — read the account, and
  place/cancel orders or delete pies if `T212_MCP_ENABLE_TRADING` is set —
  all signed with your API key. Keep it bound to `127.0.0.1` (the CLI
  default; with Docker, publish as `-p 127.0.0.1:8000:8000`) or put it
  behind an authenticating reverse proxy. Never expose it directly on a
  public or shared network.
- The server defaults to the demo (paper trading) environment; set
  `T212_ENV=live` deliberately.
- Trading tools are not registered — invisible to the MCP client — unless
  `T212_MCP_ENABLE_TRADING` is truthy.
- The Trading 212 API is v0 beta: order endpoints are **not idempotent**
  (resending a request may create duplicate orders), and rate limits are
  strict and per-endpoint (each tool documents its limit).
- Use at your own risk. Nothing here is investment advice.

## Development

```bash
uv sync
uv run pytest -q
uv run ruff check .
```

## License

MIT