qjtrader-mcp

For Claude web, mobile, or another hosted assistant, prefer the hosted QJTrader OAuth connector offered inside QJ Gateway. It provides delegated per-user access without putting QJ_CLIENT_SECRET in chat. This package is the local/stdio implementation for Claude Code and controlled local runtimes.

Model Context Protocol server for the QJ Trader AI Trading APIs. Point your LLM at your QJ credential and it can watch live Canadian and selected US market data and place simulated orders — no code, no manual API testing.

Built on the official qjtrader Python SDK. Talk to it from Claude Code, Claude Desktop, or any MCP-capable client:

"Check market availability, then compare CA:RY, MX:CRAU26, and US:@ESU26 in the sandbox. Show the books and explain which production permissions would be separate."

Verified selected US futures also include the canonical Treasury symbols US:@USU26 (30-Year Bond), US:@TYU26 (10-Year Note), and US:@FVU26 (5-Year Note).

Verifiable releases. qjtrader-mcp is published straight from this repository via PyPI Trusted Publishing with signed PEP 740 provenance — no manual uploads, no stored tokens. Before you let an agent install it, you (or the agent) can confirm each release was built by QJTrader/qjtrader-mcp from the Provenance section on PyPI. See SECURITY.md.

Safety model — AI trades simulated by default

Order-mutating tools (place_order, cancel_order, replace_order, cancel_all) use the Gateway's authenticated session response as the authority. Sandbox, paper, and shadow credentials cannot be mistaken for live credentials by a stale local setting. Canary and live credentials are refused unless you explicitly opt in.

QJ_ENV is now an optional expected-environment assertion, not the source of truth. If it disagrees with the Gateway, mutations stop with an explanation. Every tool result includes an environment tag, and order quantity is capped client-side by QJ_MCP_MAX_QTY (default 25).

Install

Get a self-serve sandbox credential at gateway.qjtrader.ai. Paid Production service is contracted and entitled separately.

The zero-install path is:

uvx qjtrader-mcp        # or: pipx run qjtrader-mcp

For local development against the SDK checkout:

# from the qjtrader-mcp/ directory, with the qjtrader-python sibling checked out:
uv sync && uv run qjtrader-mcp          # uv resolves qjtrader from ../qjtrader-python
# — or with pip —
pip install -e ../qjtrader-python -e .
qjtrader-mcp

Configure your client

Claude Code

claude mcp add qjtrader -- uvx qjtrader-mcp
# then set the credential + environment for the server:
claude mcp add qjtrader \
  -e QJ_CLIENT_ID=your-client-id \
  -e QJ_CLIENT_SECRET=your-client-secret \
  -e QJ_ENV=sandbox \
  -- uvx qjtrader-mcp

Claude Desktop / generic stdio

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "qjtrader": {
      "command": "uvx",
      "args": ["qjtrader-mcp"],
      "env": {
        "QJ_CLIENT_ID": "your-client-id",
        "QJ_CLIENT_SECRET": "your-client-secret",
        "QJ_ENV": "sandbox"
      }
    }
  }
}

The console's "Connect your AI" panel generates these blocks pre-filled, including QJ_ENV=sandbox.

Tools

market_availability also returns an observation_contract and source-aware data_shapes. Agents must preserve null or silence as "unquoted now," treat orders/venues on depth levels as optional, and never infer Greeks, NAV, contract terms, depth, or order authority from the security type alone. Canadian get_depth results include rounded Top5, odd/special-lot views, entitled order_bids/order_asks QJ/TMX TL2 rows, and source timing/provenance. Check meta.stale and meta.transport_age_ms before acting: a connected source can still be delayed by an uplink backlog, reported as meta.stale_reason="transport_backlog". Initial cached books expose meta.cached_snapshot=true and meta.snapshot_age_ms; report that age separately from relay latency. History and statistics also carry source=synthetic|recorded|unavailable plus availability. Production never substitutes generated bars when capture is absent. Production market memory follows attention: bars accumulate while a symbol is observed, while a continuous pin keeps a standing watch and richer event capture. Use watch(..., all_venues=true) to request consolidated plus every entitled Canadian venue book with one logical root. The read-only data_doctor tool reports the exact server expansion, CBBO, per-venue readiness, transport-age distribution, stale observations, and truncation without placing an order. | get_quote | read | Top-of-book (best bid/ask) for one or more symbols | | get_depth | read | Level-2 order book for a symbol (venue-tagged on consolidated books) | | watch | read | Sample the live stream for a bounded window; returns a digest + last messages | | data_doctor | read | Validate all-venue expansion, CBBO, freshness, completeness, and truncation without trading | | list_orders | read | This credential's open orders + session state | | list_trades | read | This credential's individual fills and broker cancel/correct adjustments, with account and strategy-run attribution | | get_account_activity | read | Account-wide working orders and retained executions, including Desktop/other-route activity, with freshness and history coverage | | get_positions | read | Broker-truth positions (broker + fill = total), cloud-route and Desktop-profile safeguards, estimated capital in current positions, and order plane | | place_order | write | Submit a limit order and wait for a terminal state | | cancel_order | write | Cancel a working order by cid | | replace_order | write | Amend a working order's qty/price | | cancel_all | write | Cancel every working order (kill switch) | | explain_symbol | util | Parse/explain a symbol (prefix + root + venue), offline | | read_events | read | Order journal — cross-order event history; post-trade analysis & strategy debugging | | get_history | read | Historical OHLCV bars (1s/1m) with synthetic/recorded/unavailable provenance | | get_stats | read | Server digest plus the same history provenance (a digest, not a dump) | | get_recording_status | read | Explain whether a symbol is ready, observed now, or kept in continuous memory | | get_market_events | read | Retrieve recorded quotes, trades, Level 2, and exchange events for sub-second research | | get_close_flow | read | Retrieve normalized MX Basis Trade on Close lifecycles across recorded contracts | | get_auction_imbalance | read | Retrieve authoritative Canadian-equity MOC imbalance history and aggregated closes | | get_settlement_flow | read | Retrieve normalized MX daily settlement summaries across recorded contracts | | get_recording_policy | read | Explain current standing, scheduled, and client-additive recording decisions | | keep_recording | data setting | Keep an entitled production symbol recording after apps disconnect; cannot trade | | stop_recording | data setting | Remove continuous memory and return to automatic observation-driven bars | | get_chain | read | Options chain snapshot for an underlying/expiry (latest or historical) | | compare | read | Rank a digest metric (vwap/volume/realized_vol/spread_mean) across symbols |

The read_*/get_* research tools make the LLM a quant developer: analyse the market and debug the strategy it wrote, without touching the production order path.

Configuration reference

License

Apache-2.0. See LICENSE.