Content
# tradelocker-mcp-server
(JCW)
NOTE:
Ask your AI agent to: |
|
"Fix the starlette issue and get the best performance possible from MCP." |
----------------------------------------------------------------------------
# tradelocker-mcp-server
An [MCP](https://modelcontextprotocol.io/) server that exposes a TradeLocker
trading account (account state, instruments, quotes, history, orders, sessions)
to Claude and other MCP-compatible clients.
Talks to the official [TradeLocker public REST API](https://public-api.tradelocker.com/)
directly — no third-party SDK in between — so every endpoint is reachable and
nothing breaks if the SDK falls behind.
Pairs naturally with the [tradingview-mcp](../) chart-reading server: Claude
can read levels off your TradingView chart and place / monitor orders on
TradeLocker through the same conversation.
## What's in the box
24 tools, all prefixed with `tl_`:
| Category | Tools |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discovery / config | `tl_list_profiles`, `tl_get_config`, `tl_search_instrument`, `tl_resolve_symbol`, `tl_get_instrument_details` |
| Account | `tl_get_account`, `tl_get_all_accounts`, `tl_get_account_details` |
| Quotes / market data | `tl_get_quote`, `tl_get_ask`, `tl_get_bid`, `tl_get_daily_bar` |
| History | `tl_get_price_history` (compact summary by default) |
| Read positions / orders | `tl_get_positions`, `tl_get_orders`, `tl_get_orders_history` |
| Sessions | `tl_get_session`, `tl_get_session_status` |
| Trading (DESTRUCTIVE) | `tl_create_order`, `tl_modify_order`, `tl_cancel_order`, `tl_cancel_all_orders`, `tl_modify_position`, `tl_close_position`, `tl_close_all_positions` |
Two named profiles — `demo` and `live` — let one running server talk to both
your test and your funded account. Order-modifying tools on the `live` profile
are blocked unless `TL_ALLOW_LIVE_ORDERS=true` is set explicitly.
## Architecture
```
Claude ──MCP/stdio──▶ tradelocker_mcp.server (FastMCP, 24 tools)
│
▼
tradelocker_mcp.session (per-profile JWT, accNum,
│ config columns, instrument
│ + route cache)
▼
tradelocker_mcp.rest (httpx async client →
{env}.tradelocker.com/backend-api)
```
Compact array responses from `/orders`, `/positions`, `/ordersHistory`,
`/state` are decoded into named-field dicts using the column schemas from
`/trade/config` (cached per profile).
## Requirements
- Python 3.11+
- A TradeLocker login (email + password + server name)
## Install
```bash
git clone https://github.com/jasonwilliams/tradelocker-mcp-server
cd tradelocker-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
## Configure
Copy the template and fill in your credentials:
```bash
cp .env.example .env
$EDITOR .env
```
The minimum to be useful is one full profile. Example:
```env
TL_DEFAULT_PROFILE=demo
TL_ALLOW_LIVE_ORDERS=false
TL_DEMO_ENVIRONMENT=https://demo.tradelocker.com
TL_DEMO_SERVER=GATESFX
TL_DEMO_USERNAME=trader@example.com
TL_DEMO_PASSWORD=hunter2
TL_DEMO_ACCOUNT_ID=2130973
TL_LIVE_ENVIRONMENT=https://live.tradelocker.com
TL_LIVE_SERVER=GATESFX
TL_LIVE_USERNAME=trader@example.com
TL_LIVE_PASSWORD=correcthorsebatterystaple
TL_LIVE_ACCOUNT_ID=709458
```
### A note on white-label brokers (GATESFX, etc.)
If your broker is a white-label deployment (you log in with `server="GATESFX"`),
TradeLocker still routes auth through `https://demo.tradelocker.com` and
`https://live.tradelocker.com`. The custom OMS endpoints your broker provided
(`bsa-oms.tradelocker.com:8443`, `bsb-oms.tradelocker.com:8443`, etc.) are
used internally by the platform — you do not pass them as `environment`.
The standard URLs work because `server="GATESFX"` does the routing.
If your broker tells you to use a different base URL, override
`TL_DEMO_ENVIRONMENT` / `TL_LIVE_ENVIRONMENT`.
### Demo without a password
If your demo account was provisioned without a password (some prop firms hand
out trial accounts that auth via their own portal), the REST API still
requires a password. Either ask GATESFX support for a password reset, or use
your live credentials against the demo `environment` URL — the same login
typically works on both demo and live for a given broker.
### Optional: developer API key
If you join the [TradeLocker Developer Program](https://tradelocker.typeform.com/devprogram)
you get a `tl-developer-api-key` for higher rate limits. Set it in
`TL_DEVELOPER_API_KEY` and the server attaches it to every request.
## Run
```bash
tradelocker-mcp # console script
# or
python -m tradelocker_mcp # equivalent
```
The server speaks MCP over stdio.
## Wire it into Claude
### Claude Code / Cowork (`.mcp.json`)
```json
{
"mcpServers": {
"tradelocker": {
"command": "python",
"args": ["-m", "tradelocker_mcp"],
"env": {
"TL_DEFAULT_PROFILE": "demo",
"TL_ALLOW_LIVE_ORDERS": "false",
"TL_DEMO_ENVIRONMENT": "https://demo.tradelocker.com",
"TL_DEMO_SERVER": "GATESFX",
"TL_DEMO_USERNAME": "...",
"TL_DEMO_PASSWORD": "...",
"TL_DEMO_ACCOUNT_ID": "2130973"
}
}
}
}
```
A complete two-profile example lives in `examples/claude_code.mcp.json`.
### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%/Claude/claude_desktop_config.json` (Windows) and merge the
`mcpServers` snippet from `examples/claude_desktop_config.json`. Restart Claude
Desktop.
## Safety model
- Every write tool (`tl_create_order`, `tl_modify_*`, `tl_cancel_*`,
`tl_close_*`) carries `destructiveHint: true`.
- When the _resolved_ profile is `live`, every write tool checks
`TL_ALLOW_LIVE_ORDERS`. If unset or `false`, the tool returns an error and
no API call is made.
- Credentials never appear in tool inputs — they're read from the environment.
- The server logs to stderr only (stdout is the MCP transport).
- Tools always return a `{"ok": true|false, ...}` envelope; no raw tracebacks
ever reach the model.
## Combining with TradingView
A typical "should I take this trade?" flow:
1. `chart_get_state` (TV) → confirm symbol/timeframe.
2. `data_get_pine_lines` (TV) → key levels.
3. `tl_resolve_symbol` (TL) → bridge TV symbol to broker `tradableInstrumentId`.
4. `tl_get_quote` (TL) → broker-side price.
5. `tl_get_positions` (TL) → existing exposure.
6. Propose → user confirms → `tl_create_order` (TL).
## Develop
```bash
ruff check src tests
pytest -v
```
## License
MIT — see [LICENSE](./LICENSE).
## Disclaimer
This software places real orders on real accounts. Test thoroughly on a demo
account before enabling live trading. The author is not your broker, your
financial advisor, or responsible for your trades.
THIS IS NOT FINANCIAL ADVICE DO NOT TRADE REAL RISK. THIS IS MADE AS A DATA SCIENCE TOOL USE AT OWN RISK. (JCW)
