TradePilot 212

简体中文 · English

TradePilot 212 is a self-hosted MCP application for Trading 212 Invest. It connects a personal Trading 212 account to ChatGPT or Claude. It adds deterministic performance, income, cost and allocation analytics, rebalancing, protective orders and investment plans, all behind a configurable policy engine. It provides a compact portfolio and trade-plan UI. Every Live broker write still needs an explicit confirmation.

Each deployment belongs to one user. Your Trading 212 credentials stay in your own environment; the repository owner does not run a shared brokerage backend.

Design goals

• Conversation-first workflow — works in ChatGPT, Claude, and Claude Code; use symbols, company names, amounts, percentages, or exact quantities in normal conversation.

• Explicit execution boundary — analysis and order preparation are read-only; a broker write happens only after confirmation in the app UI.

• Self-hosted by default — Cloudflare Workers is the recommended hosted path; Node.js and Docker/VPS are also supported.

• Small runtime surface — the Worker handles account access, instrument resolution, validation, state, and execution. Research and scheduling stay outside the broker bridge.

• Recoverable failures — ambiguous write outcomes are never retried automatically and can be checked against current broker state.

• Portable UI — responsive inline/fullscreen layouts, an in-flow order workspace that does not depend on fixed iframe overlays, English and Simplified Chinese, with an extensible locale registry.

Try it first: turn on sample data to explore every feature on a simulated account with no Trading 212 key, then move to your Demo account. See docs/TRY_IT.md.

Related MCP server: Trading 212 MCP Server

What is included

• Trading 212 Invest account summary, positions, pending orders, and recent TradePilot activity

• the holdings as a sortable table (by value, the day's move, profit or loss, or name) or as a map: one tile per holding, sized by its value and coloured by its move on the day or its return since bought; a tile opens the holding (docs/ANALYTICS.md)

• the day's move of every holding and of the account: each holding's price against its previous close, with the profit or loss in your currency and shares bought or sold that day counted from their fill price; before the open and over a weekend it is the last session's move. Each instrument's page shows its own, and the daily digest leads with it (docs/ANALYTICS.md)

• a page per holding: position and share of the account, a price chart of the last year's daily closes with your buys and sells marked on it and the average cost, open stops and limits and alert levels drawn across it, a price ladder of the same levels, the last year of fills and dividends, and its trade journal

• a watchlist of instruments you follow, held or not: the price now, the change over a day, a month, three months or a year, a three-month line, where the price sits in its 12-month range, the nearest open order or alert, the move since you added it and your note; add from search or from any instrument's page (docs/WATCHLIST.md)

• a trade journal: why you made each trade, written with the order or later on its fill, and what came of it looking back, kept in TradePilot and tied to the Trading 212 order; a Journal tab sets each reason against how the trade has gone since and shows per tag how often your reasons went your way (docs/JOURNAL.md)

• performance, dividend/interest income, trading costs, trade history (including cancelled and rejected orders), itemised dividends and cash movements, and allocation/concentration analysis computed from Trading 212 history (docs/ANALYTICS.md)

• order follow-up from the chat: one order's status and fills, and a cancellation opened in the widget for you to confirm

• market-hours awareness, including a warning when a Market order would queue until the next open

• a policy engine: position-weight cap, daily order and value budgets, ticker and instrument-type lists, closed-market Market-order blocking, reference-price age (docs/AUTOMATION.md)

• order baskets: up to 20 orders validated together and confirmed once, sells first, stopping on an uncertain result

• target-weight rebalancing that sizes the trades from broker prices and available cash; saved targets show their drift in the widget, notify when it grows past a threshold and rebalance in one click, or invest spare cash in the underweight targets without selling (docs/AUTOMATION.md)

• broker-native stop-loss and take-profit orders (Good-Till-Cancel), linked so that when one fills TradePilot cancels the other

• fill notices for open orders, including ones placed in the Trading 212 app: filled (with the average price), partly filled, or closed without a fill, in the activity log and to the webhook (docs/AUTOMATION.md)

• weekly or monthly investment plans that wait for your confirmation when due, with Market or gap-capped Limit legs, or one amount split across your saved targets so the most underweight holdings get the most; Demo plans can optionally run unattended

• Trading 212 pies: value, return, dividends, goal progress and drift from target for every slice; create, update, duplicate and delete pies after confirmation (docs/PIES.md)

• price alerts on holdings or any quoted instrument (above / below a price, a day's move either way from the previous close that arms itself again each trading day, trailing drop from the high, gain or loss against average cost), checked every minute

• account alerts: the account value or the free cash at or above / at or below an amount, or the whole account moving a percent in a day either way, added on the automation page or by asking (docs/AUTOMATION.md)

• a built-in sample account (TRADEPILOT_SAMPLE_DATA=true) for trying everything without an API key (docs/TRY_IT.md)

• quotes for instruments you do not hold from a pluggable source (free Stooq by default, or Finnhub, Twelve Data or Alpha Vantage with your key), used by price alerts, plans, rebalancing and the journal review

• optional webhook notifications (Slack, Discord or your own endpoint) for due plans, sent orders, fills, price and account alerts and unclear results, plus an optional daily account digest with the day's move, the dividends paid since the last one and those expected in the coming week

• an automation overview in the widget: plans, price and account alerts, linked pairs, today's budget use and settings

• expected dividend income for the next 12 months from each holding's trailing payments, as a dividend calendar (paid this month and expected per month) with each payment's approximate date, and a holding's next payments on its page

• an account value chart from TradePilot's own daily record (Trading 212's API has no value history)

• your time-weighted return against an index fund's over the same days, the S&P 500 by default or any ETF you hold or watch, as a second line on the return chart with the gap in percentage points (docs/ANALYTICS.md)

• risk on the Performance tab: volatility, return over volatility, beta and correlation to the benchmark, best and worst days, and a chart of how many days moved by how much (docs/ANALYTICS.md)

• your position on each holding's page: its value at each daily close beside the net put in (the shares held at the start, plus buys less sells), so you see what the price did for it whatever you traded (docs/ANALYTICS.md)

• monthly returns: the time-weighted return in each calendar month and year, as a year-by-month grid tinted green and red (docs/ANALYTICS.md)

• drawdown: the deepest fall of the time-weighted return from a high, when it was made up, how far below its high it is now, and the benchmark's deepest fall over the same days, as a third view of the return chart (docs/ANALYTICS.md)

• where a period's gain came from: each instrument's gain over 1 month, 3 months, this year, 12 months or all history (value now against its value at the start, its buys, sells and dividends), as bars either side of zero (docs/ANALYTICS.md)

• an annualized money-weighted return (XIRR) and a tax-year summary with realised gains and losses kept apart, dividends, interest and costs (docs/ANALYTICS.md)

• a Claude Code plugin with a local stdio server and review, brief, risk, journal, order follow-up, rebalance and tax-year skills (docs/CLAUDE_PLUGIN.md)

• a local preview of the widget on the sample account (pnpm preview), with language, theme and screen-width switches (docs/TRY_IT.md)

• separate Demo and Live credentials and UI states

• short / medium / long trade-plan cards

• expandable thesis, catalysts, risks, counter-case, sources, and data timestamps

• ticker, symbol, ISIN, company-name, and partial-name resolution

• price sanity checks: a Limit or Stop price ten times off the last price (a pence/pounds slip) is blocked, and a stop that triggers at once or a limit that fills at once is called out

• order sizing by:

  • exact quantity

  • target monetary amount

  • percentage of available cash for buys

  • percentage of the total held position for sells

  • all currently tradable shares for sells

• Market, Limit, Stop, and Stop-Limit order drafts

• transparent intent-to-quantity conversion with manual-edit indication

• reference-price freshness notices

• structured errors rendered in the selected UI language

• one-time confirmation state and no automatic write retries (only a write Trading 212 refused with 429 is sent once more)

• read-back verification after an uncertain order/cancellation response

• OAuth + PKCE for the MCP connection

• Cloudflare Durable Objects or local file-backed state through the same StateStore contract

Requirements

• Node.js 22+

• pnpm 11+

• a Trading 212 Invest account with Public API access

• a Cloudflare account for the recommended hosted deployment

• a ChatGPT or Claude plan that supports custom connectors with MCP Apps, or Claude Code for the local plugin

Install pnpm if needed:

npm install -g pnpm@11

Setup

1. Clone and install

git clone https://github.com/Kukutx/TradePilot212.git
cd TradePilot212
pnpm install

2. Create local configuration

pnpm setup

pnpm setup creates .env.local if it does not already exist and generates strong local values for the OAuth login password and signing secret.

Open .env.local and add the Trading 212 environments you intend to use:

T212_DEMO_API_KEY=
T212_DEMO_API_SECRET=

T212_LIVE_API_KEY=
T212_LIVE_API_SECRET=

Demo and Live use separate Trading 212 credentials. Configure either one or both.

Trading 212 API documentation:

• https://helpcentre.trading212.com/hc/en-us/articles/14584770928157-Trading-212-API-key

• https://docs.trading212.com/

For portfolio-only use, read permissions are sufficient. Order review/execution requires the corresponding order permissions on the Trading 212 API key.

3. Check the configuration

pnpm doctor

This checks the runtime, local OAuth configuration, and Trading 212 connectivity with read-only requests. It does not place an order.

4. Deploy a personal Worker

pnpm deploy

The deployment command:

1. validates the local configuration and project,

2. opens Cloudflare authentication when required,

3. synchronizes the instance settings through Worker Secrets,

4. builds the app,

5. deploys the Worker,

6. prints the App and MCP endpoints.

Typical output:

App: https://tradepilot212.<your-subdomain>.workers.dev
MCP: https://tradepilot212.<your-subdomain>.workers.dev/mcp

Check the deployment without publishing it:

pnpm deploy -- --dry-run

Use a different Worker name:

pnpm deploy -- --name=my-tradepilot

5. Connect ChatGPT or Claude

In ChatGPT, open the Apps settings and create a custom MCP connection. In Claude, add a custom connector. Use the /mcp URL printed by the deployment command.

The OAuth page asks for the APP_LOGIN_PASSWORD stored in your own .env.local. Do not paste Trading 212 API credentials into ChatGPT.

To use TradePilot only from Claude Code on your own computer, skip the deployment and install the plugin instead:

/plugin install tradepilot212 --marketplace Kukutx/TradePilot212

See docs/CLAUDE_PLUGIN.md.

After the connection is established, normal prompts can be simple:

Show my Trading 212 Live portfolio.
How much have I made this year, after fees? How much did I pay in FX fees?
How much dividend income did I get in the last 12 months?
Am I too concentrated? Flag anything above 15%.
Is the US market open right now?
Analyze Nvidia in the context of my current positions.
Compare AMD, Nvidia, and Broadcom for a one-month horizon.
Prepare a Demo order for 0.2 shares of NVDA.
Use about €100 to buy Nvidia in Live.
Sell half of my Apple position.
Sell all currently tradable Apple shares.
Prepare a 220 USD limit buy for 0.5 NVDA. Do not submit it.

TradePilot resolves and normalizes the request into an editable quantity-based order. The broker write still requires the final confirmation in the UI.

Order flow

User request
  ↓
Instrument resolution + account/position read
  ↓
Sizing and editable order draft
  ↓
Server validation + data freshness notices
  ↓
Short-lived one-time confirmation
  ↓
Explicit user confirmation
  ↓
Trading 212 write

If a write times out or returns an ambiguous server error, TradePilot does not resend it. The UI offers a read-only status check that looks for a matching pending order or a corresponding position change. An inconclusive result remains inconclusive; it is never converted into an automatic retry.

See docs/ORDERING.md for the sizing rules and edge cases.

Automation levels

Price and account alerts and webhook notifications run at every level; they only notify and never trade.

Live never places an order unattended; that is enforced in code, not configuration. The only unattended Live write is cancelling the other half of a stop-loss / take-profit pair after one fills (turn off with PROTECTIVE_OCO=false). Live orders and baskets also need a second, explicit confirmation that real money is used. Research and news stay in a scheduled ChatGPT or Claude task. See docs/AUTOMATION.md.

Configuration

Common instance settings:

DEFAULT_TRADING_ENV=demo
MAX_ORDER_NOTIONAL=5000
MAX_ORDER_QUANTITY=100000
CONFIRMATION_TTL_SECONDS=90

DEFAULT_TRADING_ENV applies only when a request does not explicitly select Demo or Live.

MAX_ORDER_NOTIONAL is in the account currency. An order in another currency is converted at the rate implied by your holdings, or, for a currency none of them is priced in, at the quote source's rate; pence (GBX) count at 100 to the pound. When no rate is known at all, the order is blocked while the cap is on instead of being compared in its own currency: pass fxRate (instrument-currency units per 1 account-currency unit) with fxRateAt, or set MAX_ORDER_NOTIONAL=0.

Set MAX_ORDER_NOTIONAL=0 or MAX_ORDER_QUANTITY=0 to disable the corresponding TradePilot application-level cap. Trading 212 account/instrument rules and explicit confirmation still apply.

OAuth clients may register any HTTPS redirect address by default (loopback addresses are always allowed for local tools). To accept only the hosts you use, list them:

OAUTH_REDIRECT_HOSTS=chatgpt.com,.claude.ai   # .claude.ai is claude.ai and its subdomains

Policy rules (POLICY_*) bind Live by default. A typical Live setup:

POLICY_MAX_POSITION_WEIGHT=0.2
POLICY_DAILY_ORDER_LIMIT=10
POLICY_DAILY_NOTIONAL_LIMIT=3000
POLICY_ALLOWED_TYPES=ETF,STOCK
POLICY_MARKET_ORDERS_WHEN_CLOSED=false

All policy variables are described in docs/AUTOMATION.md.

Notifications are optional:

NOTIFY_WEBHOOK_URL=https://hooks.slack.com/services/…
NOTIFY_WEBHOOK_SECRET=        # optional HMAC signature
NOTIFY_EVENTS=                # optional, e.g. plan_due,price_alert_triggered
DIGEST_HOUR_UTC=7             # optional daily digest at 07:00 UTC

The Performance tab compares the return with the S&P 500 (SPY) by default; BENCHMARK=VWRLl_EQ picks another fund (map non-US listings in QUOTE_SYMBOLS) and BENCHMARK=none turns it off.

Local development

Node development server:

pnpm setup
# fill .env.local
pnpm doctor
pnpm dev

Local MCP endpoint:

http://localhost:8000/mcp

For temporary ChatGPT testing from a local Node process:

pnpm dev:chatgpt

This uses a Cloudflare Quick Tunnel. The URL is temporary; use a normal Worker deployment for a stable personal endpoint.

Local Cloudflare runtime:

cp .dev.vars.example .dev.vars
# fill .dev.vars
pnpm dev:cloudflare

Validation

pnpm check
pnpm smoke
pnpm audit --prod
pnpm release:check
pnpm deploy -- --dry-run

The repository CI runs type checking, tests, production builds, dependency audit, release-safety checks, and a Wrangler deployment dry run.

Architecture

ChatGPT / MCP host
        │
        ▼
  Hono + OAuth/PKCE
        │
        ▼
 TradingService ─┬─ Trading212Client ── Trading 212
 InsightsService ┤        ▲
 AutomationService ─ policy · rebalance (pure)
        │
        ▼
    StateStore            ← Cron Trigger / interval: due plans
     ├─ file-backed state (Node)
     └─ Durable Object / SQLite (Workers)

React App UI ← MCP App resource

The core does not depend on the Node filesystem or Cloudflare APIs. Runtime-specific concerns live under src/adapters/.

More detail: docs/ARCHITECTURE.md.

Self-hosting model

User A → User A's ChatGPT → User A's Worker → User A's Trading 212 credentials
User B → User B's ChatGPT → User B's Worker → User B's Trading 212 credentials

Do not publish a personal deployed Worker as a shared endpoint for unrelated users. A multi-user hosted service requires separate identity, credential isolation, and authorization architecture that this repository intentionally does not implement.

See docs/PUBLISHING.md.

Security notes

• .env.local, .dev.vars, .data, build output, and Wrangler state are excluded from Git.

• Trading 212 API credentials are deployed as Worker Secrets, not source configuration.

• Demo and Live credentials are separate.

• order, basket and cancellation confirmations are short-lived and one-time.

• the policy engine runs at review and again at execution; a blocked order never receives a token.

• Live investment plans cannot be set to run unattended.

• write requests are never automatically retried after an ambiguous response.

• order constraints are revalidated immediately before submission.

• recent activity stores order metadata only; it does not store API credentials.

• the confirmation step stops the model from trading on its own, but anyone holding your connection password can trade; read the threat model before adding Live credentials.

Run pnpm release:check before publishing changes.

See SECURITY.md.

Project layout

src/
├─ adapters/
│  ├─ cloudflare/       Workers + Durable Objects + Static Assets
│  └─ node/             Node server + file-backed state
├─ app/                 shared HTTP/MCP application
├─ core/                OAuth, MCP tools, broker client, trading rules, state
├─ shared/              runtime-neutral contracts and metadata
└─ ui/                  React MCP App UI and locale dictionaries

scripts/                 setup, diagnostics, deployment, smoke checks
docs/                    architecture, ordering, automation, publishing, i18n
.github/workflows/        CI

License

MIT. See LICENSE.

Disclaimer

TradePilot 212 is a software integration project, not investment advice. Review market information and every order yourself. Trading 212 controls API availability, permissions, instruments, and broker-side limits, and those may change independently of this repository.