# Questrade MCP Server

An [MCP](https://modelcontextprotocol.io/) server for the Questrade trading API.
Use it from MCP-compatible clients (Claude, ChatGPT, Cursor, and others) to inspect
portfolio data, quotes, market history, orders, and account activity.

This server is designed around outcome-oriented tools: each tool performs the
necessary Questrade API orchestration internally so agents can get complete results
with fewer round-trips.

## Table of Contents

- [Quick Start](#quick-start)
- [MCP Features](#mcp-features)
- [Tools](#tools)
- [Configuration](#configuration)
- [Token Management](#token-management)
- [Real-Time Data Notes](#real-time-data-notes)
- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
- [Docker](#docker)
- [CI/CD](#cicd)
- [Security](#security)
- [Contributing](#contributing)
- [Security Policy](#security-policy)
- [Release Process](#release-process)
- [License](#license)

## Quick Start

### Prerequisites

- Node.js 22+
- A [Questrade](https://www.questrade.com/) account with API access enabled

### 1) Clone, Install, Build

```bash
git clone https://github.com/DrWheelicus/questrade-mcp-server.git
cd questrade-mcp-server
npm install
npm run build
```

### 2) Get a Questrade Refresh Token

1. Open the [Questrade API Hub](https://www.questrade.com/api)
2. Register a personal app (or reuse an existing one)
3. Enter a name for the device and a description
4. Click **Create**
5. Select **New device**
6. Select **Generate new token**
7. Copy the refresh token and paste it into the .env file

> [!WARNING]
> The refresh token is a secret and should not be shared.
> If you lose it, you will need to generate a new one. (Steps 5-7)

### 3) Add Server to Your MCP Client

Use a config like this (replace with your local absolute path):

```json
{
  "mcpServers": {
    "questrade": {
      "command": "node",
      "args": ["/absolute/path/to/Questrade/dist/index.js"],
      "env": {
        "QUESTRADE_REFRESH_TOKEN": "<your-token>"
      }
    }
  }
}
```

Common locations:

- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- Claude Code: project `.mcp.json` or `~/.claude/mcp.json`
- Cursor: Settings -> MCP Servers

> [!NOTE]
> On some Windows MSIX installs, Claude Desktop may read a virtualized config path instead:
> `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`.

### 4) Verify

Restart your MCP client and ask:

> Show me my portfolio

## MCP Features

- **Tools**: purpose-built portfolio and market data operations
- **Transport support**: `stdio` for local clients, Streamable HTTP for remote clients
- **Validation**: tool inputs validated with Zod schemas
- **Token lifecycle management**: encrypted persistence and automatic refresh

This server currently exposes MCP **tools** (not prompts/resources).

## Tools

| Tool | Description |
| ---- | ----------- |
| `getPortfolio` | Full portfolio overview across accounts with positions and balances |
| `getPositions` | Positions held in a specific account |
| `getBalances` | Cash balances and buying power for an account |
| `lookupSymbol` | Search by ticker/name and return symbol details plus live quote |
| `getQuotes` | Batch Level 1 quotes by ticker names or symbol IDs |
| `getPriceHistory` | Historical OHLCV candles at intervals from 1 minute to yearly |
| `getOrders` | Order history with state and date filters |
| `getAccountActivity` | Combined activities and executions timeline |

## Configuration

All runtime configuration is environment-driven:

| Variable | Required | Default | Description |
| -------- | -------- | ------- | ----------- |
| `QUESTRADE_REFRESH_TOKEN` | Yes (first run) | - | OAuth refresh token from Questrade |
| `QUESTRADE_ENVIRONMENT` | No | `production` | `production` or `practice` |
| `QUESTRADE_MCP_TRANSPORT` | No | `stdio` | `stdio` or `http` |
| `QUESTRADE_MCP_PORT` | No | `3100` | Port for HTTP transport |
| `QUESTRADE_ENCRYPTION_KEY` | No | machine-derived | Override encryption key for token storage |
| `LOG_LEVEL` | No | `info` | `fatal`, `error`, `warn`, `info`, `debug`, `trace` |

The CLI flag `--transport` overrides `QUESTRADE_MCP_TRANSPORT`.

### HTTP Mode (Remote Clients)

```bash
QUESTRADE_REFRESH_TOKEN=<your-token> node dist/index.js --transport=http
```

Server endpoint:

- `http://localhost:3100/mcp`

## Token Management

Questrade uses single-use refresh tokens. This server:

1. Exchanges the initial refresh token on first startup
2. Encrypts and stores token material with AES-256-GCM
3. Renews access proactively before expiry
4. Retries once on `401` responses after refreshing

Token storage paths:

| Platform | Path |
| -------- | ---- |
| Windows | `%APPDATA%\questrade-mcp\token.enc` |
| macOS | `~/Library/Application Support/questrade-mcp/token.enc` |
| Linux | `~/.config/questrade-mcp/token.enc` |

After first successful startup, `QUESTRADE_REFRESH_TOKEN` is only needed again if the cached token expires.

## Real-Time Data Notes

Questrade requires a paid market data subscription for real-time quotes.
Without one, `getQuotes` returns snap quotes with daily exchange limits and may
fall back to delayed data. Use `isDelayed` in quote responses to detect this.

## Development Setup

```bash
npm install
npm run dev
npm run build
npm run lint
npm run typecheck
npm test
```

### MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Project Structure

```text
.
├── src/
│   ├── index.ts                # Server entrypoint and transport selection
│   ├── server.ts               # MCP server and tool registration
│   ├── config.ts               # Env/config parsing
│   ├── log.ts                  # Logger setup
│   ├── auth/                   # Token persistence and refresh
│   ├── client/                 # Questrade API client and rate limiting
│   ├── tools/                  # MCP tool implementations
│   ├── transports/             # stdio and HTTP transport handlers
│   └── types/                  # Shared API/domain types
├── tests/                      # Unit/integration tests
├── .github/workflows/          # CI/CD workflows
└── Dockerfile
```

## Docker

Build and run HTTP transport:

```bash
docker build -t questrade-mcp .
docker run -p 3100:3100 -e QUESTRADE_REFRESH_TOKEN=<your-token> questrade-mcp
```

## CI/CD

- **CI** on push/PR to `main`: type check, lint, build, tests, `npm audit`, dependency review
- **CD** on tags matching `v*.*.*`: multi-arch Docker image to GHCR and GitHub Release

## Security

- Token material encrypted at rest (AES-256-GCM)
- Refresh tokens rotated by design (Questrade behavior)
- Token values redacted from logs
- Read-only server scope (no trade placement tools)
- Input validation on all tool parameters (Zod)
- HTTP transport uses per-client session isolation
- Docker image runs as non-root user

## Contributing

See `CONTRIBUTING.md` for contributor setup, quality checks, and PR process.

GitHub issue and PR templates are provided in `.github/` to keep reports and reviews consistent.

## Security Policy

See `SECURITY.md` for how to report vulnerabilities privately.

## Release Process

See `RELEASE.md` for the tag-based release checklist and verification steps.

## License

Proprietary - All Rights Reserved.

No permission is granted to copy, modify, redistribute, sublicense, or use this
code except with explicit written permission from the copyright holder.