trading212-mcp

A Model Context Protocol server for the Trading 212 Public API. It exposes your Trading 212 account — balances, positions, orders, history, and pies — as tools an MCP-capable AI client can call, letting the assistant read your portfolio and place trades on your behalf.

Runs locally on your own machine, against your own account. Supports both paper-trading (demo) and real-money (live) environments.

⚠️ This software places real trades with real money when run in live mode. It is provided as-is, with no warranty. Read the Security and Disclaimer sections before using it live. Requires an Invest or Stocks ISA account — the Trading 212 API does not support CFD accounts.

Contents

• Features
• Important information
• Requirements
• Installation
• Configuration
• Running the server
• Connecting a client
• Tools
• Troubleshooting
• Security
• Disclaimer
• License

Features

• Full coverage of the public API — account, instruments, positions, orders, history, and pies.
• Two environments — demo (paper) and live (real money), selected at launch.
• Client-side rate limiting that respects Trading 212's per-endpoint limits.
• Confirmation prompts before any trade or destructive action on the live account.
• Cursor-based pagination surfaced through simple cursor / nextCursor fields.

Important information

• You choose demo or live when you start the server — a connected client cannot change it. The server binds to whichever environment you launched it with until you stop and restart it.
• Demo is paper trading; live moves real money. Everything the assistant does in live mode happens in your real account.
• On live, every trade and destructive action requires your explicit confirmation before it runs, and failed orders are never retried automatically — a retry could place the same trade twice.
• Every tool response records which environment produced it, so there is never ambiguity about whether a result came from demo or live.
• The server has no authentication. Anyone who can reach its port can use it — see Security.

Requirements

• Node.js 18 or later.
• A Trading 212 Invest or Stocks ISA account.

No other system dependencies — everything else is installed by npm.

Installation

git clone https://github.com/t0knight/trading212-mcp.git
cd trading212-mcp
npm install

Configuration

Generate API keys in the Trading 212 app under Settings → API (Beta). Demo and live are separate key pairs — see the official guide.

The server reads its credentials from these environment variables:

Variable	Used when running against
T212_DEMO_API_KEY / T212_DEMO_API_SECRET	demo (paper trading)
T212_LIVE_API_KEY / T212_LIVE_API_SECRET	live (real money)

Only the pair for the environment you actually run is required.

The simplest way to supply them is a .env file in the project root, which the server loads automatically at startup:

T212_DEMO_API_KEY=your-demo-key
T212_DEMO_API_SECRET=your-demo-secret
T212_LIVE_API_KEY=your-live-key
T212_LIVE_API_SECRET=your-live-secret

Any credentials already present in the environment take precedence over the file.

Running the server

The server listens on http://127.0.0.1:<port>/mcp. There are two main ways to run it.

Option 1 — as a background service (recommended)

Running it as a service means your operating system starts the server automatically and keeps it running in the background, so it's always available and you never have to launch it by hand. macOS does this with launchd; Linux with systemd. Setting one up is a standard task for your platform with plenty of guides online — the steps below are only the parts specific to this project.

1. Build the project. From the project folder, run:

   npm run build
   

   This compiles the source into a dist/ folder. You only need to repeat this if you update the code.

2. Set the service's command. The service should launch the compiled server with full paths (services don't start inside your project folder, so relative paths won't resolve):

   /full/path/to/node /full/path/to/trading212-mcp/dist/index.js --env demo --port 8212
   

   which node prints the first path; the second is wherever you cloned the project. Change demo to live for real-money trading, and the port if 8212 doesn't suit.

3. Provide the credentials. If your .env file is in the project folder, nothing more is needed — the server finds it next to its own code regardless of how it was started. Alternatively, set the variables from Configuration directly in the service definition; values set there override the file.

4. Install and start the service using your platform's normal method (launchctl on macOS, systemctl on Linux). To confirm it's up, run curl http://127.0.0.1:8212/mcp — any reply, even an error message, means the server is listening; no reply means it isn't running.

Option 2 — from the terminal

For occasional use or quick testing, launch it directly with the helper script:

./start.sh            # demo, port 8212 (defaults)
./start.sh live       # live
./start.sh live 9000  # live on a custom port

The script builds the project and starts the server in the foreground, with every request logged to the terminal — useful for watching what a connected assistant is actually doing. Stop it with Ctrl+C.

Connecting a client

MCP clients typically connect to a local server by launching a command and talking to it. Register the server in your client's MCP configuration with this command:

npx -y mcp-remote http://127.0.0.1:8212/mcp --allow-http

What it does: the client launches mcp-remote, a small adapter that relays everything to the server running at http://127.0.0.1:8212/mcp. npx downloads and runs it on demand (-y skips the download prompt), and --allow-http permits an unencrypted connection, which is fine here because the traffic never leaves your machine.

Every client has its own way of registering MCP servers — a config file, a settings screen, or a CLI command — and its own place for it, so check your client's documentation. Wherever it goes, the command above is the entire configuration; adjust the port if you changed it, and restart the client afterwards. The server must be running for the client to see the tools.

If your client can connect to a streamable-HTTP MCP endpoint directly by URL, you can skip the adapter and point it straight at http://127.0.0.1:8212/mcp.

Once connected, ask your assistant things like:

• "What's my current unrealized P/L?"
• "Find the ticker for the Vanguard FTSE All-World ETF."
• "Show my dividends from the last year, then total them by instrument."

Tools

Tool	Description
get_account_summary	Cash, invested value, total value, realized/unrealized P/L
search_instruments	Search tradable instruments by ticker, name, or ISIN
get_exchanges	Exchanges and their trading-hour schedules
get_positions	Open positions with P/L and wallet impact
get_pending_orders / get_order	List active orders, or fetch one by ID
place_market_order	Trade immediately at the next available price
place_limit_order	Execute at a target price or better
place_stop_order	Market order triggered at a stop price
place_stop_limit_order	Limit order triggered at a stop price
cancel_order	Cancel a pending order by ID
get_order_history	Executed orders with fills (paginated)
get_dividends	Dividends paid out (paginated)
get_transactions	Cash movements — deposits, withdrawals, fees (paginated)
list_report_exports / request_report_export	Generate and retrieve CSV reports
get_pies / get_pie	List pies, or one pie with per-instrument detail
create_pie / update_pie / duplicate_pie / delete_pie	Manage pies and target allocations

A few conventions carried over from the Trading 212 API:

• Selling uses a negative quantity on any order tool.
• Orders execute only in the account's primary currency.
• Paginated tools return a nextCursor; pass it back as cursor to fetch the next page (null means the last page).
• Updating a pie's allocation changes its targets only — it does not trade to rebalance immediately.
• The pie endpoints are deprecated by Trading 212: still functional, but no longer supported and subject to change.

Each API key carries per-category scopes (account, metadata, orders, portfolio, history, pies). If a tool returns a 403, the response names the scope to enable under Settings → API.

Troubleshooting

• The server won't start: "address already in use". Another process is on the port — usually a previous instance of this server. Stop it, or launch on a different port.
• Tools return a 401 authentication error. The keys don't match the environment the server is running in — demo and live have separate key pairs, so check the right pair is set and has no typos or stray whitespace.
• Tools return a 403 error naming a scope. Your API key was created without that permission. Enable the named scope for the key in the Trading 212 app under Settings → API.
• The client doesn't show any tools. Confirm the server is running (curl http://127.0.0.1:8212/mcp — any reply means it's up), then restart the client; most only read their MCP configuration at startup.

Security

This server has no authentication and no transport encryption. It trusts any client that can reach its port. On the live environment, that means anyone who can connect can place and cancel real trades.

Keep it bound to localhost (the default). Never expose it on a public IP, a cloud host, or an internet-facing tunnel without first putting proper authentication and HTTPS in front of it. Prefer demo for development, and treat live as you would any credential that can move money.

Disclaimer

This is an independent project, not affiliated with or endorsed by Trading 212. The Trading 212 API is in beta and may change without notice. Use at your own risk — you are solely responsible for any trades placed through this tool, including any financial loss.

License

Released under the MIT License.