# Trading 212 MCP Server

An MCP (Model Context Protocol) server that wraps the [Trading 212 Public API v0](https://docs.trading212.com/api), enabling AI agents to interact with your Trading 212 brokerage account through natural language.

## Features

**16 tools** across 5 categories:

| Category | Tools | Description |
|---|---|---|
| **Accounts** | `get_account_summary` | Cash breakdown, investment metrics, total value |
| **Instruments** | `get_instruments`, `get_exchanges` | Tradable instruments and exchange schedules |
| **Positions** | `get_open_positions` | All open positions with P&L and wallet impact |
| **Orders** | `get_pending_orders`, `get_order_by_id`, `place_market_order`, `place_limit_order`, `place_stop_order`, `place_stop_limit_order`, `cancel_order` | Full order lifecycle management |
| **History** | `get_historical_orders`, `get_dividends`, `get_transactions`, `request_csv_report`, `get_reports` | Historical data with pagination and CSV export |

## Prerequisites

1. A Trading 212 **Invest** or **Stocks ISA** account
2. API key + secret generated from the Trading 212 app (Settings → API)
3. Node.js ≥ 18

## Setup

```bash
# Clone and install
cd trading212-mcp
npm install

# Build
npm run build
```

## Configuration

Set these environment variables before running:

| Variable | Required | Description |
|---|---|---|
| `T212_API_KEY` | ✅ | Your Trading 212 API key |
| `T212_API_SECRET` | ✅ | Your Trading 212 API secret |
| `T212_ENV` | ❌ | `demo` (default) or `live` |

## Usage with Claude Desktop / Gemini CLI

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "trading212": {
      "command": "node",
      "args": ["c:/GenAI/trading212-mcp/dist/index.js"],
      "env": {
        "T212_API_KEY": "your_api_key",
        "T212_API_SECRET": "your_api_secret",
        "T212_ENV": "demo"
      }
    }
  }
}
```

## Usage with VS Code / Copilot

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "trading212": {
      "command": "node",
      "args": ["c:/GenAI/trading212-mcp/dist/index.js"],
      "env": {
        "T212_API_KEY": "your_api_key",
        "T212_API_SECRET": "your_api_secret",
        "T212_ENV": "demo"
      }
    }
  }
}
```

## Development

```bash
# Run in development mode (no build step)
npm run dev
```

## ⚠️ Important Notes

- **Default environment is `demo`** (paper trading) — no real money at risk
- **Order tools are NOT idempotent** — duplicate calls create duplicate orders
- **Sell convention**: use a negative quantity (e.g. `-10.5` sells 10.5 shares)
- All rate limits are enforced per-account by Trading 212's servers
- API is currently in **beta** — see [Trading 212 API docs](https://docs.trading212.com/api)

## License

MIT