Repository navigation
API and MCP
stonks serve runs a REST API over the same services the CLI uses. stonks mcp lets Claude talk to that API.
flowchart LR
WEB[Web console] --> API
CL[Claude Code / Desktop] -->|stdio| MCP[stonks mcp]
MCP -->|HTTP + token| API[stonks serve<br/>127.0.0.1:8000]
API --> SVC[app services]
SVC --> DB[(lake + state)]
export STONKS_API_TOKEN=pick-a-long-random-string
uv run stonks serve # http://127.0.0.1:8000
uv run stonks serve --host 0.0.0.0 --port 9000 --reloadIt also serves the built web console from web/dist when present.
- The token comes only from the
STONKS_API_TOKENenv var, never from a config file. - Reading (GET) from the same machine needs no token (
open_reads_on_loopback = true). - Anything that changes something needs
Authorization: Bearer <token>. - No token configured means every write is refused.
- It binds to
127.0.0.1by default, and only accepts known Host headers (allowed_hosts).
| Prefix | For |
|---|---|
/api/health |
Liveness probe and health report |
/api/auth |
Token check |
/api/alerts |
Alerts feed |
/api/portfolio, /api/pnl
|
Current portfolio, snapshots, P&L |
/api/strategies |
List, detail, promote, shadow, retire, go-live checks, P&L |
/api/shadow |
Shadow decisions and virtual P&L |
/api/market |
Instruments, bars, data coverage |
/api/ingest |
Ingest runs; start an ingest |
/api/lab |
Start backtests and lab runs, results, cost models |
/api/ticks |
Tick history; start a tick |
/api/orders |
Orders and fills |
/api/studio |
Strategy Studio drafts |
/api/catalog |
Strategies with parameter specs, intervals, asset classes |
/api/risk, /api/brokers, /api/sources
|
Risk policy, broker info, data sources |
/api/jobs |
Background jobs |
The OpenAPI contract is in web/openapi.json. Every route is listed on API Reference and in the Swagger UI.
Not yet in the API: users and login, subscriptions, broker connections, push subscriptions and metrics. Those are CLI or service only for now (see Accounts and Modes).
Long work (backtest, lab run, ingest, tick) returns a job right away.
-
POST /api/lab/runsreturns a job id. - Poll
GET /api/jobs/{id}, or stream progress with server-sent events at/api/jobs/{id}/events. - Browsers cannot send the bearer header to an event stream, so first call
POST /api/jobs/{id}/stream-tokenfor a short-lived URL. - Cancel with
POST /api/jobs/{id}/cancel.
Up to max_concurrent_jobs (2) backtests and lab runs run at once. Ticks and ingests each have their own worker.
MCP (Model Context Protocol) lets an AI assistant call tools. stonks mcp never opens the databases; it calls the running API. Start stonks serve first.
Register with Claude Code, from the repo root:
claude mcp add stonks --env STONKS_API_TOKEN=your-token -- uv run --directory "$(pwd)" stonks mcpClaude Desktop (claude_desktop_config.json):
{"mcpServers": {"stonks": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\Stonks", "stonks", "mcp"],
"env": {"STONKS_API_TOKEN": "your-token"}}}}| Kind | Tools |
|---|---|
| Read | portfolio, P&L, strategies, reports, bars, orders, ticks, catalog, jobs, health, ... |
| Jobs | backtests, lab runs, ingest |
| Guarded writes | promote, shadow, retire, tick, Studio drafts |
The full, generated list is on MCP Tools.
- Guarded writes without
confirm: trueonly return a preview. -
run_tickis a dry run unless you passdry_run: false, and a real tick is refused unless the API reports a simulated or paper broker. - No tool changes config or enables live trading.
- The token is never sent over plain
httpto a non-local host.
More: docs/mcp.md in the repo.
Source: sleousis/Stonks. Plans and status: docs/roadmap.md.
Start
Concepts
- Architecture
- Data and Storage
- Strategies
- Book Strategies
- Lab and Validation
- Backtesting
- Accounts and Modes
Using Stonks
- Strategy Studio
- Trading Tick
- Risk and Go-Live
- Operations
- Scheduling and Backups
- Deploy
- API and MCP
- Web Console
Reference