broker-state-mcp

A small, read-only MCP server that gives Claude grounded access to live brokerage state across two venues — Alpaca (equities/crypto) and Kraken (crypto spot) — so an agent can answer "what's my exposure?" from data instead of guessing from prose.

Seven typed tools. Zero that can place, modify, or cancel an order.

get_account                 Alpaca equity, buying power, cash, day P&L
get_positions               Alpaca open positions with unrealized P&L
get_recent_orders           Alpaca order history, newest first
get_kraken_balance          Kraken per-asset balances + total USD value
get_kraken_positions        Kraken coin holdings (non-stable, dust filtered)
get_kraken_recent_trades    Kraken fills, newest first
get_exposure_summary        Both venues in one call, with a combined USD figure

Why it exists

I run automated trading bots with real (small) money and use Claude Code as an operator console over them. Early on, the model would estimate positions from log excerpts and be confidently wrong. This server replaces inference with a tool call.

Related MCP server: Alpaca API MCP Server

Design decisions

Read-only by construction, not by instruction. There is no order-placement tool because there is no order-placement code. A prompt injection, a hallucinated tool name, or a careless bypassPermissions run cannot reach a mutating endpoint that does not exist. Telling a model "please don't trade" is a request; not shipping the capability is a guarantee.

Per-venue fault isolation. get_exposure_summary wraps each venue independently. If Kraken is rate-limiting, you still get Alpaca, with the Kraken error surfaced in-band rather than the whole call failing. For an operator dashboard, partial truth with an explicit gap beats a stack trace.

Lazy Kraken client. The ccxt client is constructed on first use, so the server starts (and the Alpaca tools work) even if Kraken credentials are absent. The Alpaca headers are read at import time because a missing key there should fail loudly and early — the two venues have different failure philosophies on purpose.

Dust filtering. get_kraken_positions drops holdings under min_usd (default $1). A grid bot accumulates fractional leftovers; they are noise in an exposure view.

Install

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

Register with Claude Code (user scope). Use the paper Alpaca endpoint until you have a reason not to:

claude mcp add broker-state -s user \
  -e ALPACA_KEY_ID=... -e ALPACA_SECRET_KEY=... \
  -e ALPACA_BASE_URL=https://paper-api.alpaca.markets \
  -e KRAKEN_API_KEY=... -e KRAKEN_API_SECRET=... \
  -- "$PWD/.venv/bin/python3" "$PWD/server.py"

Credentials are read from the environment only. Nothing is written to disk.

Use read-only API keys. Both Alpaca and Kraken let you scope a key to query-only permissions. This server never needs more, so do not give it more — defense in depth is cheap here.

Example

"What's my total exposure right now?"

{
  "alpaca":  { "account": { "equity": 975.74, "day_pl": 0.52, ... }, "positions": [ ... ] },
  "kraken":  { "balance": { "assets": { "USD": {...}, "USDT": {...} }, "total_usd": 438.26 },
               "positions": [] },
  "combined_usd": 1414.00
}

Transport

stdio. Run it directly to sanity-check it starts:

ALPACA_KEY_ID=x ALPACA_SECRET_KEY=x .venv/bin/python3 -c "import server; print('ok')"

License

MIT