Firstrade

A Model Context Protocol server that gives an LLM (Claude, or any other MCP host) read/write access to a Firstrade brokerage account: live positions, balances, quotes, option chains/greeks, order history, and — if you choose to enable it — order placement (stocks, single-leg options, and two-leg option spreads).

Built on top of the community firstrade Python package, which reverse-engineers Firstrade's internal api3x web API. This project is not affiliated with, endorsed by, or supported by Firstrade.

⚠️ Read this before you use it

• Firstrade has no official public trading API. This server (like the firstrade package it depends on) works by driving the same private endpoints the Firstrade web app uses, authenticated with your real login. That is very likely outside the spirit — and possibly the letter — of Firstrade's Terms of Service around automated / unauthorized access. Your account could be flagged, rate-limited, or suspended. Use at your own risk, on an account you're prepared to lose access to.
• The order-placement tools (place_stock_order, place_option_order, place_option_spread) send real orders with real money. There is no simulated/paper mode. This is enforced server-side, not just by convention: place_* is disabled unless FT_ALLOW_LIVE_ORDERS=true is set in .env, and every call additionally requires a confirm_token minted by the matching preview_* tool for the identical order — a mismatched or missing token is rejected before anything is sent. See Live order safety model.
• This is a personal tool the author built for their own workflow and is sharing as-is. It is not a product, has no support SLA, and comes with no warranty of any kind (see LICENSE). Nothing here is investment advice.
• Options trading requires an appropriately approved options level on your Firstrade account (e.g. naked calls need Level 2+ margin approval) — the broker enforces this server-side and will reject anything you're not approved for.

If any of that gives you pause, it should — read it twice before you put real credentials in .env.

What it does

Tool	Purpose
get_account_position	Live stock + option positions, all accounts
get_account_balance	Equity, cash, buying power
get_account_history	Transaction history (fills, dividends, interest, transfers) — presets or a custom date range
get_orders	Open/filled/cancelled orders, with the Firstrade order id
get_single_quote / get_watchlist_quote	Real-time quote(s)
get_option_chain	Broker's own option chain; omit the expiration to list available expirations
get_option_greeks	Broker-computed delta/gamma/theta/vega/rho + IV for a chain
preview_stock_order / place_stock_order	Stock orders — buy, sell, sell_short, buy_to_cover; limit/market/stop/stop-limit/trailing
preview_option_order / place_option_order	Single-leg option orders — buy_to_open, sell_to_open, sell_to_close, buy_to_close
preview_option_spread / place_option_spread	Two-leg option spreads (debit or credit), priced by net price
cancel_order	Cancel an open order by id

Every place_* tool has a matching preview_* tool that runs the identical request in dry-run mode. The intended usage pattern for an LLM host is: always preview first, show the user the preview, only place after explicit confirmation — and the server enforces this, it doesn't just document it (see below).

Live order safety model

place_stock_order, place_option_order, and place_option_spread are gated by two independent checks, both server-side:

1. Kill switch. They refuse to run unless FT_ALLOW_LIVE_ORDERS=true is set in .env. Unset (the default) or anything else, and every place_* call returns an error without touching the network — preview_* still works, so you can wire this up and see previews before ever flipping the switch.
2. Preview→place confirmation token. Every preview_* call mints a one-time confirm_token bound to the exact order arguments (symbol, side, quantity, price, duration, etc.), valid for 10 minutes. The matching place_* call must pass that token back unchanged. A missing token, an expired token, or a token minted for different order arguments (e.g. the LLM previewed 10 shares but tries to place 100) is rejected before the order reaches Firstrade. Tokens live in-process only — a server restart invalidates every pending preview.

This closes the gap where "preview first" was only a docstring instruction an LLM host could skip or a permissions layer could bypass; now placing an order that was never (or differently) previewed is impossible at the code level.

Two more things worth knowing:

• duration on stock orders defaults to gt90 (Firstrade's ~90-day GTC), which the confirm-token flow forces you to see in the preview before it can be sent. Pass duration="day" explicitly if you don't want a resting GTC order.
• If your login has more than one Firstrade account, order/quote/cancel tools refuse to guess which one you mean — set FT_ACCOUNT_NUMBER in .env.

See docs/option-order-api.md for the reverse-engineered schema of Firstrade's single-leg and multi-leg option order endpoints (error codes, field validation behavior, GTC vs day-only constraints), discovered via the probe scripts in tools/.

Prerequisites

• Python 3.12+
• uv (recommended; plain pip install -e . also works)
• A Firstrade account, and an authenticator app if you want headless session refresh (see below)

Setup

git clone https://github.com/PatrickSUDO/firstrade-mcp-server.git
cd firstrade-mcp-server
uv sync
cp .env.example .env
# edit .env: fill in FT_USERNAME, FT_PASSWORD, FT_PIN, FT_EMAIL
# leave FT_ALLOW_LIVE_ORDERS unset until you've reviewed the safety model below

First login (interactive)

Firstrade requires 2FA (OTP or authenticator MFA) on every fresh login. Run this once to establish a session:

uv run python3 tools/ft_setup.py step1
# → sends an OTP / prompts for your authenticator code
uv run python3 tools/ft_setup.py step2 <CODE>

This saves session cookies to ~/.local/share/firstrade-session. server.py reuses that saved session on every tool call, so you don't re-auth per request.

Optional: headless session refresh

Firstrade sessions expire periodically. If you set FT_TOTP_SECRET in .env (the seed your authenticator app was set up with — not the 6-digit code), the server self-heals automatically: it detects a dead session (401) and re-runs the login + TOTP flow without a human typing anything. You can also trigger this manually:

uv run python3 tools/ft_setup.py auto

Without FT_TOTP_SECRET, a dead session falls back to the manual step1 / step2 <code> flow above.

Register with an MCP host

Claude Code:

claude mcp add firstrade-server -- uv --directory /absolute/path/to/firstrade-mcp-server run server.py

Generic mcp.json / host config:

{
  "mcpServers": {
    "firstrade-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/firstrade-mcp-server", "run", "server.py"]
    }
  }
}

Credentials are read from firstrade-server/.env at startup — you don't need to (and shouldn't) put them in the MCP host config.

Security notes

• No credentials are hardcoded anywhere in the source. server.py and tools/ft_setup.py both load FT_* values from a local .env file that is git-ignored.
• FT_TOTP_SECRET, if you set it, is your authenticator's full seed — not a 6-digit code. Anyone with it (or with your .env) can mint valid login codes for your account indefinitely, no phone required. Treat .env like a password, not a config file: chmod 600 it, don't sync it anywhere shared.
• The saved session (~/.local/share/firstrade-session) and the transient login-flow state (~/.local/share/firstrade-session-tmp/) hold live cookies / tokens. Both are written with 0600/0700 perms and kept out of /tmp (which is world-readable on most multi-user machines). ft_setup.py also never prints raw tokens/cookies to stdout — only redacted shapes — since a failed headless re-auth surfaces its tail through the MCP error channel.
• uv.lock is committed and firstrade is pinned to an exact version, not a floating >=. This wraps an unofficial, reverse-engineered API client that runs against a live brokerage account — bump it deliberately, after testing, not automatically on uv sync.
• tools/probe-out/ (raw API responses captured while reverse-engineering the option order schema) is git-ignored too — even though account numbers in those responses are masked by Firstrade itself, it's still your own live session output.
• Review .gitignore before you fork/extend this and make sure your own .env, session cache, and any new debug-output directories stay out of git.

License

MIT. Provided as-is, for personal/educational use. Not investment advice. Not affiliated with Firstrade.