Trading 212 client + MCP

Connect Node.js applications and AI assistants to the Trading 212 public API. Typed requests, bounded history, account snapshots, and opt-in trading in two independently installable packages.

Independent community project; not affiliated with Trading 212. Requires Node.js 22.18+. MIT licensed.

Package	Use it for	Guide
@mingchuno/trading212-client	Trading 212 access from JavaScript or TypeScript	Client usage
@mingchuno/trading212-mcp	Local stdio tools for an MCP-compatible assistant	MCP setup

Use with an assistant

Check the server can run:

npx --yes @mingchuno/trading212-mcp --version

Add a local stdio server to your MCP host. This common JSON format is host-dependent; replace the credential path with your own:

{
  "mcpServers": {
    "trading212": {
      "command": "npx",
      "args": ["--yes", "@mingchuno/trading212-mcp"],
      "env": {
        "T212_ENV": "live",
        "T212_CREDENTIALS_FILE": "/absolute/private/path/trading212.json",
        "T212_ALLOW_TRADING": "false"
      }
    }
  }
}

For Codex, add this to ~/.codex/config.toml:

[mcp_servers.trading212]
command = "npx"
args = ["--yes", "@mingchuno/trading212-mcp"]

[mcp_servers.trading212.env]
T212_ENV = "live"
T212_CREDENTIALS_FILE = "/absolute/private/path/trading212.json"
T212_ALLOW_TRADING = "false"

See MCP setup for creating the credentials file, checking the connection, and troubleshooting executable paths. No repository clone or development tooling is needed.

To keep plaintext credentials out of local configuration files, see the password-manager environment injection alternative, with 1Password examples in JSON and TOML.

Try asking: “Summarize my positions and pending orders” or “Find instruments matching Apple.” Trading starts disabled; report generation remains available.

Use from code

npm install @mingchuno/trading212-client

import { Trading212Client } from '@mingchuno/trading212-client';

const client = new Trading212Client({
  environment: 'live',
  apiKey: process.env.T212_API_KEY,
  apiSecret: process.env.T212_API_SECRET,
});

console.log(await client.account.summary());

Supply the environment variables before running your ESM application. See client usage for pagination, errors, and trading configuration.

Tools

Tool	Behavior
connection_status	Verify summary access; report environment and configured trading flag
account_snapshot	Summary, positions, and pending orders with independent timestamps/errors
get_positions	Current positions, optional exact ticker filter
search_instruments	Bounded ticker/name/ISIN metadata search
get_exchanges	Cached exchange schedules
list_pending_orders	Current pending orders, optional ticker filter
get_pending_order	One pending order by ID
get_history	One page of orders/dividends/transactions, maximum 50 items
list_reports	Report status and available download links
request_report	Start CSV generation; available with trading disabled
place_order	Market/limit/stop/stop-limit; requires trading enabled
cancel_order	Request cancellation; requires trading enabled

List tools expose bounds and continuation information. History continuation uses the returned nextPagePath with the same kind, without overriding filters. Metadata is cached for ten minutes and reports its fetch time. Snapshots are not atomic; offset pagination over current positions/orders is not a frozen view.

Trading behavior

Set T212_ALLOW_TRADING=true outside tool arguments to enable placement/cancellation in the selected environment. Host-side approval is required for the intended user experience; tool annotations and descriptions are advisory, not an authorization system. Do not configure your host to auto-approve real-money trading unless that is your intended policy.

Orders use an exact Trading 212 ticker, explicit buy/sell, and a positive share quantity. The client translates sells to negative API quantities and validates order-specific fields. It does not provide quotes, guarantee buying power, or estimate fills.

No mutations are automatically retried. OUTCOME_UNKNOWN means a request may already have been applied: inspect pending orders and history before deciding what to do. Absence from pending orders alone cannot prove rejection. Cancellation acceptance is only a request, not proof of completed cancellation. CSV generation is asynchronous; use list_reports after its suggested polling interval. Download links may be sensitive; the server does not download or forward credentials to them.

The upstream API is beta, supports Invest/Stocks ISA, and has primary-currency limitations. Deprecated Pie operations are available in the client but omitted from MCP. See design boundaries and upstream references.

Development

Development uses the tool versions in mise.toml. TypeScript stays pinned because the generator requires its JavaScript compiler API.

mise install
pnpm install --frozen-lockfile
pnpm build
pnpm verify             # regeneration drift, Biome, types, fixtures, build
pnpm format             # format/lint fixes in maintained code
pnpm spec:update        # explicitly download upstream JSON
pnpm generate           # normalize snapshot and regenerate SDK
pnpm test               # deterministic tests; no broker credentials required
pnpm test:coverage      # maintained-source coverage: terminal, HTML, LCOV, JSON
pnpm pack:smoke         # install local tarballs in a temporary consumer (npm registry access)

Upstream JSON is preserved in openapi/trading212.json. Generation applies documented corrections in scripts/normalize-spec.mjs; never edit src/generated manually. JSON is the canonical input; YAML is the alternate upstream format. Generation details.

Fixture tests protect mutation gates and exact order payloads, uncertain outcomes and retry limits, active-request cancellation/timeouts, history traversal, cache lifecycle, credential-file rejection, and MCP tool results. They do not establish broker-side execution behavior. For an authenticated smoke check, run doctor against your chosen account. Test order placement separately in demo before using live trading.

GitHub Actions runs pnpm verify on pushes, pull requests, and manual dispatches using the mise tool pins. CI uses fixtures and needs no Trading 212 credentials. Verification generates coverage and the Verify workflow uploads the report as a 14-day artifact, including when tests fail. Open coverage/index.html locally. Coverage excludes generated SDK code and has no percentage threshold: critical behavioral assertions are the gate. CLI subprocess smoke tests run separately and are not represented in the Vitest coverage totals.

Releases

Husky and CI enforce Conventional Commits. Release Please manages independent package versions and changelogs; merging its release PR publishes through npm trusted publishing once configured. See release maintenance.