Skip to main content
Glama
questrade-mcp

questrade-mcp

by agustinsacco
README.md
# Questrade MCP

A read-only Model Context Protocol server for [Questrade](https://www.questrade.com).
It covers Questrade's whole read API: accounts, balances, positions, activities,
executions, orders, symbols, quotes, option chains with Greeks, candles and
markets. It adds technical analysis and portfolio reports across accounts, and
keeps responses small enough that a model can page through years of activity
without flooding its context.

> Not affiliated with Questrade. Read-only by design: no tool places, changes
> or cancels orders.

## What it can do

| Area | Tools | What you get |
|---|---|---|
| Context | `qt_get_context`, `qt_list_accounts` | sign-in state and command, accounts, default account, server time |
| Balances | `qt_get_balances` | cash, market value, equity, buying power; per currency and combined; start of day |
| Positions | `qt_list_positions` | quantity, cost, price, value, open/day P&L, currency, weight; totals per currency |
| Activity | `qt_list_activities` | trades, dividends, deposits, withdrawals, interest, fees, FX; any date range; filters; totals |
| Fills and orders | `qt_list_executions`, `qt_list_orders`, `qt_get_order` | fills with commission and fees; order history and one order in full |
| Symbols and quotes | `qt_search_symbols`, `qt_get_symbols`, `qt_get_quotes`, `qt_list_markets` | tickers to IDs, fundamentals (P/E, EPS, yield, 52-week range), live quotes with change, market hours |
| Options | `qt_get_option_chain`, `qt_get_option_quotes` | expiries, strikes near the money, IV and Greeks |
| Price history | `qt_get_candles` | stats, ASCII chart and OHLCV rows, 1 minute to 1 year candles |
| Analysis | `qt_compare_symbols`, `qt_analyze_technicals`, `qt_screen_watchlist` | % change and drawdown, RSI, SMA 50/200, VWAP, Bollinger Bands, screens |
| Reports | `qt_run_report` | portfolio summary, allocation, dividend income, activity summary (below) |

19 tools, 2 resources (`questrade://guide`, `questrade://limitations`) and 3
prompts (`portfolio_review`, `dividend_report`, `research_symbol`). Every
tool, parameter and default is listed in **[docs/TOOLS.md](docs/TOOLS.md)**,
which is generated from the server.

### Reports

`qt_run_report` works across all active accounts (or one), and every result
states its basis:

| Report | Source | Period |
|---|---|---|
| `portfolio_summary` | live balances; each account's total in CAD and USD at Questrade's rate | now |
| `allocation` | live positions combined by symbol, weights within each currency, by security type | now |
| `dividend_income` | dividend activities by symbol and by month | any range (default year to date) |
| `activity_summary` | activities by type and currency, net deposits per account, commissions | any range (default year to date) |

### How it handles Questrade's API

| Questrade behaviour | Handling |
|---|---|
| Activities allow about a month per request | Any range is split into 30-day requests, back to back with no overlap, and cached briefly |
| Times need an ISO offset and Questrade works in Eastern time | Tools take `YYYY-MM-DD` (a Toronto day) or a full date-time; offsets follow DST |
| Positions carry no currency | Added from symbol details, so totals and weights never mix CAD and USD |
| Tools take numeric symbol IDs | Tools also accept exact tickers (`XEQT.TO`, `AAPL`); unknown ones get a pointer to `qt_search_symbols` |
| Candles stop at 2000 per request | Defaults per interval stay under it; a warning says when a range was cut |
| Each refresh token works once | Rotation is shared safely between processes (see [Sign in](#sign-in)) |
| Rate limits (`X-RateLimit-Reset`) | 429s wait for the reset (at most 10 s) and retry; 5xx and network errors back off |

### What Questrade's API cannot do

See `questrade://limitations`:

- **No trading** for personal apps (and this server never trades).
- No tax lots, realized gains or tax slips: use Questrade's statements for tax
  filing.
- No watchlists and no streaming through this server.
- Quotes follow the account's market-data subscription and can be delayed.

## Install

Node.js 20 or later. Agents get two things on top of the server:
- the **`questrade-portfolio` skill** (`skills/questrade-portfolio/SKILL.md`),
  which covers first steps, sign-in, the tools and the rules;
- the **sign-in command**, which the server puts into its connector
  description, `qt_get_context` (`auth.signIn`) and every auth error, with this
  machine's real path and host name.

### pi / Phosphor: one command

```bash
pi install npm:@saccolabs/questrade-mcp          # from npm
pi install git:github.com/agustinsacco/questrade-mcp   # or straight from GitHub
```

pi installs the npm dependencies. The package's extension registers the
`questrade` MCP server for every session (codemode exposure), and the skill
joins every session's skill index. Phosphor can also install it from
Settings → Skills & extensions. Until someone signs in, each new session
shows:

```
Questrade is not signed in on <host>. In a terminal there, run: node <package>/bin/questrade-mcp.js login
```

A `questrade` entry in `mcp.json` takes precedence over the package's
registration.

### Claude Code, Claude Desktop, Cursor: no clone needed

The package is on npm as
[`@saccolabs/questrade-mcp`](https://www.npmjs.com/package/@saccolabs/questrade-mcp).
`npx` downloads and runs it:

```bash
claude mcp add --scope user questrade -- npx -y @saccolabs/questrade-mcp
```

Other clients take the same command in their config:

```json
{ "mcpServers": { "questrade": { "command": "npx", "args": ["-y", "@saccolabs/questrade-mcp"] } } }
```

Then sign in, in a terminal on the same machine:

```bash
npx -y @saccolabs/questrade-mcp login
```

Every other command works the same way (`npx -y @saccolabs/questrade-mcp check`,
`… setup`). When the server runs through npx, its sign-in messages show the
npx command too. These clients don't install the `questrade-portfolio` skill. They get the
same guide from the `questrade://guide` resource, and the start-here tool points
to it. `npx -y @saccolabs/questrade-mcp setup` adds the server and a copy of the
skill to Claude Code in one step.

### From a clone: `setup`

```bash
git clone https://github.com/agustinsacco/questrade-mcp && cd questrade-mcp && npm install
node bin/questrade-mcp.js setup
```

`setup` looks for pi and Claude Code, shows each change and asks first:
- **pi:** `pi install <this folder>`.
- **Claude Code:** `claude mcp add --scope user questrade …`, plus a link at
  `~/.claude/skills/questrade-portfolio`.

It then runs `login` and `check`. Re-running it skips whatever is already set
up, and `--yes` accepts every step without asking. For other clients (Claude
Desktop, Cursor, …) it prints the config entry to add:

```json
{ "mcpServers": { "questrade": { "command": "node", "args": ["/path/to/questrade-mcp/bin/questrade-mcp.js"] } } }
```

Clients without skills can read the same guide from the `questrade://guide`
resource. Credentials stay on the machine that runs the server, so sign in on
each machine where it runs.

## Sign in

```bash
node bin/questrade-mcp.js login
```

1. Log in at https://my.questrade.com and open App Hub → API Centre. Activate
   API access the first time.
2. Open your personal app (register one if needed), click **New manual
   authorization**, then **Generate new token**.
3. Paste the token at the hidden prompt. It is never printed.

`login` exchanges the token right away, so a mistyped or already-used token is
caught immediately. Tokens are stored outside the repository in
`~/.config/questrade-mcp/credentials.env`, mode `600` (override with
`QUESTRADE_CREDENTIALS_FILE`). Running servers pick up a new token on their
next call. Other commands:
- `check` verifies the login and lists the accounts.
- `secrets list` shows which keys are set, never their values.
- `logout` forgets the tokens. To revoke access on Questrade's side too,
  remove the authorization in the API Centre.

See [`credentials.env.example`](credentials.env.example).

**Token lifecycle.** Access tokens last about 30 minutes, and each refresh token
works once:
- Every server process reads the current access token from the credentials
  file.
- A refresh runs under a lock file and re-reads the file first, so when
  several processes (one per agent session) need a new token at once, only one
  spends the refresh token and the rest reuse its result.
- A 401 on a token another process already replaced reuses the new one.
- While a server runs it refreshes every 25 minutes, which keeps the chain
  alive. A manually generated token expires after 7 days if unused, so after a
  longer stretch with no server running, sign in again.
- Writes are atomic (temp file, fsync, rename, chmod 600).

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `QUESTRADE_ACCOUNT_ID` | auto | Default account. Otherwise the only active account; with several, tools ask for `accountId` |
| `QUESTRADE_MCP_TOOLSETS` | all | Comma list: `context,accounts,market,analysis,reports` |
| `QUESTRADE_MCP_MAX_RESPONSE_CHARS` | 60000 | Hard cap per tool result (trailing list items are dropped, with a note) |
| `QUESTRADE_MCP_MAX_RANGE_DAYS` | 3660 | Longest activity/execution/order range one call may fetch |
| `QUESTRADE_MCP_CACHE_TTL_MS` | 60000 | Cache for account data, ranges and candles |
| `QUESTRADE_MCP_MAX_CONCURRENCY` | 4 | Concurrent Questrade requests |
| `QUESTRADE_MCP_TIMEOUT_MS` / `QUESTRADE_MCP_MAX_RETRIES` | 30000 / 3 | Per request |
| `QUESTRADE_MCP_NO_KEEPALIVE` | off | Skip the 25-minute refresh while the server runs |
| `QUESTRADE_MCP_LOG_LEVEL` | info | `debug`, `info`, `warn`, `error`, `silent` (stderr only) |
| `QUESTRADE_MCP_HTTP_HOST` / `_PORT` / `_PATH` | 127.0.0.1 / 8788 / /mcp | HTTP transport |
| `QUESTRADE_MCP_ALLOWED_HOSTS` | loopback | Host/Origin allow-list for HTTP |
| `QUESTRADE_MCP_HTTP_TOKEN` | — | Bearer token for HTTP (credentials file); required off loopback |
| `QUESTRADE_CREDENTIALS_FILE` | `~/.config/questrade-mcp/credentials.env` | Credentials file (`QUESTRADE_TOKEN_FILE`, the 1.x name, still works) |

## Use it

Ask things like "what's my allocation across TFSA and RRSP?", "how much did I
get in dividends last year, by month?", "show my trades in XEQT this year",
or "compare XEQT.TO, VFV.TO and AAPL over 3 years". The prompts give ready-made
versions: `portfolio_review`, `dividend_report` (year) and `research_symbol`
(symbol).

### Streamable HTTP (one server for several clients)

```bash
node bin/questrade-mcp.js serve --http                      # http://127.0.0.1:8788/mcp
QUESTRADE_MCP_HTTP_HOST=100.x.y.z QUESTRADE_MCP_ALLOWED_HOSTS=myhost,100.x.y.z node bin/questrade-mcp.js serve --http
```

Off loopback the server refuses to start without `QUESTRADE_MCP_HTTP_TOKEN`,
and clients send `Authorization: Bearer <token>`. Host and Origin headers are
validated against DNS rebinding. `GET /healthz` reports liveness.

## Response design

- **Pagination everywhere.** Lists use `page`/`pageSize` (default 20, max
  100); reports and candles use `offset`/`limit`. Every response says
  `hasMore` and gives `nextPage`/`nextOffset`.
- **Summary by default.** `detail: "summary"` returns key fields and clips
  long text; `"full"` returns every field Questrade sends.
- **Compact JSON.** Nulls, empty strings and empty lists are dropped.
- **A hard budget.** Results above `QUESTRADE_MCP_MAX_RESPONSE_CHARS` are
  trimmed, never silently.
- **Totals cover all rows** even when only a page of rows is returned.
- **Errors are tool results** (`isError: true`) whose text names the fix:
  Questrade's own message and code, the account choices when one is needed,
  unknown tickers, auth problems with the command to run.

## MCP practices followed

- Official TypeScript SDK v2 (`@modelcontextprotocol/server`), spec 2026-07-28,
  serving 2025-era clients from the same factory over stdio and Streamable HTTP.
- Zod input schemas with per-field descriptions and bounds; arguments are
  validated before handlers run.
- Tool annotations on every tool: `readOnlyHint: true`,
  `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
- Server `instructions`, resources for the guide and limitations, and
  user-invoked prompts.
- stdout carries only JSON-RPC; logs go to stderr with secrets redacted.
- Toolsets for least privilege; no tool accepts or reveals credentials.

## Security

- Read-only: no order placement, cancellation or any other write.
- Credentials live only in the mode-600 credentials file on the machine that
  runs the server. They are never in MCP arguments, logs or tool results.
  `login` and `secrets set` read them with echo off.
- Agents are told never to ask for a token in the chat, and never to run
  `login` themselves.
- HTTP binds to loopback unless a bearer token is set.

## Development

```bash
npm test          # unit + end-to-end over both transports against a fake Questrade (no network)
npm run smoke     # live, with your credentials: every tool once, against the default account
npm run docs      # regenerate docs/TOOLS.md (a test fails when it is out of date)
npm run inspect   # MCP Inspector
```

The fake Questrade (`test/helpers/fake-questrade.js`) behaves like the real
one where it matters:
- one-use refresh tokens, and only the latest access token works;
- the 31-day activity limit (error 1003);
- `{ code, message }` errors and rate limits.

The token tests run six real processes at once to prove only one spends the
refresh token.

### Releasing

CI (`.github/workflows/ci.yml`) runs the tests on Node 20, 22 and 24 for every
push and pull request. When a push to `master` has a `package.json` version
that isn't on npm yet, and the tests pass, CI publishes it with provenance,
then tags `v<version>` and creates a GitHub release. To release:

```bash
npm version minor --no-git-tag-version   # or patch / major
npm run docs                             # TOOLS.md records the version
git commit -am "x.y.z: what changed" && git push
```

A version with a hyphen, such as `1.2.0-beta.1`, goes to the `next` dist-tag.
CI publishes through npm trusted publishing, so no npm token is stored in
GitHub. It was set up once with
`npm trust github @saccolabs/questrade-mcp --repo agustinsacco/questrade-mcp --file ci.yml --allow-publish`.
A `NPM_TOKEN` repository secret also works, as a fallback.

### Migrating from 1.x

2.0 matches [wave-mcp](https://github.com/agustinsacco/wave-mcp): the same
SDK, CLI, install paths and response design. Tool names follow its
`list_`/`get_` convention:

| 1.x | 2.0 |
|---|---|
| `qt_get_accounts` | `qt_list_accounts` (or `qt_get_context`) |
| `qt_get_positions` | `qt_list_positions` |
| `qt_get_transactions` | `qt_list_activities` |
| `qt_get_orders` | `qt_list_orders` |
| `qt_lookup_symbol` | `qt_search_symbols` |
| `qt_get_quotes`, `qt_get_candles`, `qt_get_balances`, `qt_compare_symbols`, `qt_analyze_technicals`, `qt_screen_watchlist` | same names; symbols may also be tickers |

Account tools no longer fall back silently to the first account: set
`QUESTRADE_ACCOUNT_ID` or pass `accountId`. Times may be plain dates.
`src/main.js` is now `bin/questrade-mcp.js`, and the credentials file gains
the current access token, so several processes can share it.

## Related

[wave-mcp](https://github.com/agustinsacco/wave-mcp), an MCP server for Wave
accounting, works the same way: it installs the same way, signs in the same
way, and has the same CLI and response design.

## License

MIT

TDQS

B3.2/5.0

Scored across 11 tools

Disambiguation4/5

Most tools target distinct resource types: accounts, positions, balances, quotes, orders, candles, transactions, and symbol lookup. The slight overlap is among compare_symbols, analyze_technicals, and screen_watchlist, but their descriptions differentiate normalized charting, indicator calculation, and criteria-based screening well enough.

Naming Consistency5/5

Every tool uses the qt_ prefix and follows a clear verb_noun pattern, such as qt_get_accounts, qt_lookup_symbol, and qt_screen_watchlist. Although verbs vary beyond get, the convention is consistent and predictable across the entire set.

Tool Count5/5

With 11 tools, the server is well-scoped for Questrade data retrieval and analysis. Each tool serves a distinct purpose, and the count is appropriate for covering account data, market data, historical candles, and technical screening without unnecessary bloat.

Completeness4/5

The toolset covers account information, positions, balances, orders, quotes, candles, transactions, symbol lookup, comparisons, and technical analysis. It appears intentionally read-only, so order placement/cancellation is absent, but for market data and analysis workflows the coverage is strong with only minor gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues