# @luxalgo/broker-mcp

[![npm](https://img.shields.io/npm/v/@luxalgo/broker-mcp)](https://www.npmjs.com/package/@luxalgo/broker-mcp) [![CI](https://github.com/LuxAlgo/broker-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/LuxAlgo/broker-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Give your AI agent read access to your real brokerage accounts — with keys that never leave your machine.**

A local [MCP](https://modelcontextprotocol.io) server wrapping [`@luxalgo/broker-sdk`](https://github.com/LuxAlgo/broker-sdk). Connect Claude (or any MCP client) to Alpaca, Binance, Kraken, Bybit, Hyperliquid, Interactive Brokers and more, then just ask:

> *"How's my portfolio doing?" · "What's my win rate this month?" · "What did I trade last week?"*

No hosted service, no telemetry, no per-connection fees. The server runs on your machine, your keys live in your own MCP config, and the underlying SDK has **no trading endpoints at all** — the agent can look, not touch.

## Setup

Add the server to your MCP client config with the credential env vars for the brokers you use. Claude Desktop (`claude_desktop_config.json`) or Claude Code (`.mcp.json`):

```json
{
  "mcpServers": {
    "brokers": {
      "command": "npx",
      "args": ["-y", "@luxalgo/broker-mcp"],
      "env": {
        "BROKERS_ALPACA_API_KEY": "…",
        "BROKERS_ALPACA_API_SECRET": "…",
        "BROKERS_KRAKEN_API_KEY": "…",
        "BROKERS_KRAKEN_API_SECRET": "…",
        "BROKERS_HYPERLIQUID_WALLET_ADDRESS": "0x…"
      }
    }
  }
}
```

Every broker whose variables are all set is connected automatically. **Create every key with read-only scope** — that is all this server ever needs; the `list_brokers` tool includes the one-line read-only setup guide per broker.

### Environment variables

Names derive mechanically from each broker's credential fields: `BROKERS_<BROKER>_<FIELD>`.

| Broker | Variables |
| --- | --- |
| Alpaca | `BROKERS_ALPACA_API_KEY`, `BROKERS_ALPACA_API_SECRET` |
| Coinbase (BYO app) | `BROKERS_COINBASE_CLIENT_ID`, `BROKERS_COINBASE_CLIENT_SECRET`, `BROKERS_COINBASE_REFRESH_TOKEN` |
| Binance | `BROKERS_BINANCE_API_KEY`, `BROKERS_BINANCE_API_SECRET` |
| Bybit | `BROKERS_BYBIT_API_KEY`, `BROKERS_BYBIT_API_SECRET` |
| Crypto.com | `BROKERS_CRYPTO_COM_API_KEY`, `BROKERS_CRYPTO_COM_API_SECRET` |
| E\*TRADE (BYO app) | `BROKERS_ETRADE_CONSUMER_KEY`, `BROKERS_ETRADE_CONSUMER_SECRET`, `BROKERS_ETRADE_ACCESS_TOKEN`, `BROKERS_ETRADE_ACCESS_TOKEN_SECRET` |
| Hyperliquid | `BROKERS_HYPERLIQUID_WALLET_ADDRESS` |
| Interactive Brokers (Flex) | `BROKERS_IBKR_FLEX_FLEX_TOKEN`, `BROKERS_IBKR_FLEX_FLEX_QUERY_ID` |
| Kraken | `BROKERS_KRAKEN_API_KEY`, `BROKERS_KRAKEN_API_SECRET` |
| OKX | `BROKERS_OKX_API_KEY`, `BROKERS_OKX_API_SECRET`, `BROKERS_OKX_PASSPHRASE` |
| Public.com | `BROKERS_PUBLIC_API_KEY` |
| Questrade | `BROKERS_QUESTRADE_REFRESH_TOKEN` |
| Topstep | `BROKERS_TOPSTEP_USER_NAME`, `BROKERS_TOPSTEP_API_KEY` |
| Tradier | `BROKERS_TRADIER_ACCESS_TOKEN` |
| Trading212 | `BROKERS_TRADING212_API_KEY` |
| Webull | `BROKERS_WEBULL_API_KEY`, `BROKERS_WEBULL_API_SECRET` |

> **Questrade caveat:** its refresh tokens are single-use and rotate on every fetch. The server keeps the rotated token in memory while it runs, but after a restart the token in your config is already consumed — you'll need to paste a fresh one. Static env config and rotating tokens are a poor fit; a better answer is on the roadmap.

## Tools

| Tool | What the agent gets |
| --- | --- |
| `list_brokers` | Every supported broker, its env vars (set/unset — never values), configured state, read-only key guide |
| `list_accounts` | All connected accounts: broker, currency, equity, cash |
| `get_positions` | Open positions with market values (negative quantity = short); filter by broker |
| `get_trades` | Trade history, newest first; filter by broker/symbol |
| `get_stats` | Total equity, equity by broker, top positions, FIFO win rate, avg win/loss, realized PnL per symbol |
| `refresh` | Bypass the 5-minute cache and re-fetch everything now |

Snapshots are cached in memory for 5 minutes; per-broker failures are reported alongside results, never silently dropped.

## Security posture

- **Read-only by construction.** The SDK underneath implements no order, transfer, or withdrawal endpoint for any broker.
- **Keys stay in your MCP config.** The server reads them from its environment, reports only *whether* each variable is set, and never writes secrets anywhere.
- **Local only.** Talks to your brokers directly over HTTPS and to your MCP client over stdio. No LuxAlgo server involved, no telemetry.
- Still: scope every key read-only at the broker, and treat your MCP config file like the secret store it is.

## Development

```bash
pnpm install && pnpm check && pnpm build
```

The SDK dependency installs from the public npm registry like any other package.

## Disclaimer

This software reports what your broker reports. It is not investment advice. Verify important numbers against your broker's own statements.

## License

[MIT](LICENSE) © LuxAlgo