topstepx-mcp

topstepx-mcp/  v0.1   ──────────────────────────────────────────────────

A focused MCP server that lets Claude Code (or any MCP-compatible client) interact with the TopstepX prop-firm trading API — read account state, place / modify / cancel orders, manage positions, query trades, run risk checks.

Important

Not affiliated with Topstep or TopstepX. This is a personal-use bridge to the TopstepX REST + SignalR APIs. You provide your own API key.

Caution

This tool can place real orders on a real prop-firm account. Read the entire Safety section before running anything against a non-paper account. The default mode requires explicit per-tool confirmation and never opens positions without a tool call from the connected client.

---

What it does

Wraps the TopstepX REST API + SignalR realtime feed in 7 typed tool modules. Inputs and outputs validated end-to-end with Zod. Auth tokens cached locally with TTL. SignalR subscription managed automatically.

                  ┌───────────────┐
                  │ Claude Code   │
                  │ (or any MCP   │
                  │  client)      │
                  └───────┬───────┘
                          │ stdio (MCP)
                          ▼
                  ┌───────────────┐
                  │  topstepx-mcp │
                  └───┬───────┬───┘
                      │       │
              REST    │       │ SignalR (realtime)
                      ▼       ▼
                  ┌───────────────┐
                  │   TopstepX    │
                  │     API       │
                  └───────────────┘

---

Tools

Module	Tools
accounts	list accounts, get balances
contracts	search contracts, get contract details
market	get current market data, subscribe to feed
orders	place, modify, cancel orders (incl. bracket orders)
positions	list open positions, close position, partial close
risk	check account risk metrics (drawdown, daily P&L, exposure)
trades	query trade history with filters

---

Install

Requires Node.js 20+.

npm install -g topstepx-mcp
# or, in a project:
npm install topstepx-mcp

For development:

git clone https://github.com/harshil1502/topstepx-mcp.git
cd topstepx-mcp
npm install
npm run build
npm test

---

Setup

1. Get a TopstepX API key

Generate one inside the TopstepX web dashboard. The MCP needs:

• TOPSTEPX_API_KEY — your API key
• TOPSTEPX_USERNAME — your TopstepX login email

2. Configure environment

Either export them in your shell:

export TOPSTEPX_API_KEY=your_key_here
export TOPSTEPX_USERNAME=you@example.com

…or put them in a local file (default: .env in the working directory) and point the MCP at it via TOPSTEPX_ENV_PATH.

3. Wire into Claude Code

Add to ~/.claude/mcp.json (or your project .mcp.json):

{
  "mcpServers": {
    "topstepx": {
      "command": "topstepx-mcp",
      "env": {
        "TOPSTEPX_API_KEY": "your_key_here",
        "TOPSTEPX_USERNAME": "you@example.com"
      }
    }
  }
}

Restart Claude Code. The 7 tool modules are now available.

---

Example session

You:    What's my account balance and what positions are open?
Claude: [calls accounts.list, positions.list]
        Account 12345 · balance $52,340.21 · day P&L +$120 · 1 position open
        - MNQ · long 1 contract · entry 18,420 · last 18,442 · +22 ticks

You:    Close half the MNQ position with a market order.
Claude: [calls positions.partialClose with size=1, ratio=0.5]
        Submitted partial close. Filled at 18,442. Position now 0 contracts.

---

Safety

• Read the contract you're trading. Tool inputs accept any contract symbol; the MCP doesn't override your client's confirmation flow.
• Risk-check first. risk.check returns drawdown, daily P&L, and exposure — wire it into your client's pre-trade workflow.
• Cached tokens. Auth tokens are cached on disk under the OS temp directory. Delete topstepx-token-cache.json to force a fresh login.
• No order replay on reconnect. SignalR reconnections do not re-submit pending tool requests.

---

Configuration

Env var	Required	Description
TOPSTEPX_API_KEY	yes	TopstepX API key
TOPSTEPX_USERNAME	yes	TopstepX login email
TOPSTEPX_ENV_PATH	no	Path to .env-style file with the above (default: .env in cwd)

---

Development

npm install
npm run build         # tsc to dist/
npm run dev           # tsc --watch
npm test              # vitest run
npm run typecheck     # tsc --noEmit

Code structure:

src/
├── index.ts           entry — registers tools, starts stdio server
├── client.ts          REST client (auth, token cache, request helpers)
├── signalr.ts         SignalR realtime subscription manager
├── types.ts           shared types
└── tools/
    ├── accounts.ts
    ├── contracts.ts
    ├── market.ts
    ├── orders.ts
    ├── positions.ts
    ├── risk.ts
    └── trades.ts

To add a tool: drop a file in src/tools/, export Zod schemas + handler, register in src/index.ts.

---

Disclaimer

This software is provided "as is" without warranty of any kind. By running it, you acknowledge:

• You are using your own paid TopstepX account, your own API key.
• Trading futures involves substantial risk of loss. Do not let an AI agent place orders against capital you can't afford to lose.
• Topstep's account rules (drawdown, daily-loss-limit, end-of-day flat) still apply. Violation can suspend or close your account.
• This MCP does not enforce Topstep's rules — your client logic and the risk tool are your guardrails.

---

License

MIT © 2026 Harshil Patel