qjtrader-mcp 0.4.1

MCP server for QJ Trader — let an LLM inspect availability, watch Canadian and selected US data, and place simulated orders.

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."

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.

Server-declared order environment	Read tools (quotes/depth/status)	Order tools
sandbox	✅	✅ simulated
paper / shadow	✅	✅ non-exchange mutation path
canary / live	✅	⛔ unless QJ_MCP_ALLOW_LIVE=1
unavailable or mismatched	✅ where possible	⛔ fail closed

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 free sandbox credential (no approval) at gateway.qjtrader.ai.

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

Tool	Kind	Description
session_info	read	Environment, whether order actions are allowed, endpoints, authenticated user. Call first.
market_availability	read, offline	Product-by-product sandbox vs production data/order support, verified examples, and known gaps. Call before assuming a product has depth or order authority.
search_universe	read	Search current symbol forms and capability metadata by market or text
describe_instrument	read	Describe one symbol, its product identity, venue scope, and available operations
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
list_orders	read	Open orders + session state
get_positions	read	Broker-truth positions (broker + fill = total), risk envelope + admserv hard caps, capital-required, 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); sandbox = deterministic synthetic days
get_stats	read	Server digest for a symbol: VWAP, spread, volume, realized vol (a digest, not a dump)
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

Env var	Purpose	Default
QJ_CLIENT_ID / QJ_CLIENT_SECRET	credential	— (required)
QJ_ENV	Optional expected environment; mismatch refuses mutations	unset
QJ_MCP_ALLOW_LIVE	set 1 to authorize live order actions	off
QJ_MCP_MAX_QTY	client-side max order quantity	25
QJ_DATA_HOST / QJ_ORDERS_HOST	endpoint overrides	public QJ hosts
QJ_CA_FILE	pin a CA/cert (pilot order endpoint)	none

License

Apache-2.0. See LICENSE.