# flox-foundation/flox-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/FLOX-Foundation/flox/tree/main/mcp  
**GitHub Stars:** 229  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/flox-foundation-flox-mcp

## Description
MCP server for the FLOX trading systems framework. 30 tools to run backtests, scaffold strategies, validate for lookahead bias, place orders, query PnL via Claude/Cursor. C++23 core with Python/Node/Codon/QuickJS strategy bindings. Same code from backtest to live (CcxtBroker or native connectors). Install: pip install flox-mcp.

## Tools
Capabilities this server exposes over MCP:

- **lrvx_venue_guide** — Use when the user wants to BUILD A MARKET rather than trade on one: simulate several agents/strategies against one shared order book, model market impact with reacting counterparties, or run a matching engine, clearing ledger, margin/liquidation, market-data feed or venue gateway. Returns a Markdown guide to the optional lrvx venue module (lrvx::venue): headers, order vocabulary, derivatives waterfall, the multi-agent demo, build flag, and verification posture. No arguments. Cheap; pure bundled text. NOT for an ordinary single-strategy backtest over historical data -- use run_backtest.
- **lrvx_overview** — Call this FIRST when you don't know which lrvx MCP tool to use. Returns a Markdown narrative of the toolkit organised by category (discovery, building a backtest, live engine inspection, calibration), with canonical workflows for the most common tasks and a recent-additions section. No arguments. Cheap; pure bundled text. Cuts the AI-agent cycles spent rediscovering what the surface is on every fresh session.
- **list_indicators** — List every indicator exposed by the lrvx Python binding with its class signature, batch function (if any), and shape (single-input scalar, OHLC tuple, multi-output, …). Use this when the user asks 'what indicators does lrvx support' or before suggesting an indicator name.
- **lookup_error_code** — Resolve a lrvx error code (e.g. 'E_SYM_001') to its full Markdown documentation page — fix recipe, common causes, diagnostics. Use whenever a LrvxError is raised in user code; never guess at a fix from the message alone.
- **list_capi_functions** — Search the lrvx C-API surface from the committed ABI snapshot. Returns name + return type + parameter types for every exported `lrvx_*` function. Use when the user is writing FFI code (Codon, QuickJS, Rust cgo, ctypes) or asks 'what C symbols can I call'.
- **validate_strategy** — Static-analysis check on a Python lrvx strategy: AST parses, expected hooks present (on_trade / on_bar), no forbidden patterns (eval, exec, __import__ tricks). Use this before running user-authored strategy code. Does NOT execute the code.
- **explain_event** — Describe the fields of a lrvx event struct. Accepts a type name ('LrvxTradeData', 'LrvxBookData', 'LrvxBarData', 'LrvxSymbolContext', 'LrvxSignal') OR a raw event dict; returns each field's name, type, units, and human description. Use when the user asks 'what's in this event'.
- **lookup_symbol** — Resolve a lrvx symbol across every surface (C++, C-API, Python, Node, Codon, QuickJS). Methods resolve too, reported as Owner.method. Returns the local name, kind, and signature for each binding that exports it. Use this whenever the user names a struct, function, or indicator and you need to know what it's called in *their* language — never guess at the cross-language spelling. Accepts any spelling the user knows ('LrvxBarData', 'BarData', 'lrvx_indicator_ema', 'ema', 'Ema'). Filter to one language with the `language` arg if the user is writing in a specific binding. When the symbol has hand-curated semantic gotchas (silent quantization, ordering preconditions, subscribed-vs-registry distinctions), they appear under a `## Gotchas` section in the response.
- **list_bindings** — Enumerate the public exports of one lrvx binding surface (C-API / Python / Node / Codon / QuickJS). Use this when the user asks 'what does the {Python|Node|Codon} binding expose?' or when they want to browse a binding before picking a symbol. Substring filter is case-insensitive.
- **get_example** — Return canonical lrvx example code for a topic, filtered optionally by language. Use this when the user asks 'show me how to {backtest|connect to ccxt|wire an indicator}' BEFORE writing fresh code from memory — the bundled examples are CI-validated, your generated code is not. Topics: strategy, connector, indicator, event-handler, risk, backtest. Languages: python, node, codon, cpp.
- **scaffold_strategy** — Return a starter lrvx strategy class that compiles and passes `validate_strategy`. Use this as the *first* thing you write when the user asks to 'build a new strategy' — start from this canonical shell, then edit the indicator + signal logic, instead of writing the lrvx bookkeeping (constructor, hook names, signal builder) from memory. `language` is required — lrvx is polyglot and picking the binding for the user is wrong; ask which language they want first. Supported: python, node, codon, quickjs. Three kinds: bar-driven (TA on bar close), trade-driven (tick-by-tick), hybrid (both). The result includes a `Next steps` section with `docs_search` queries for the recording / backtest / layout follow-ups; follow them in order.
- **init_project** — Create a new lrvx project from a bundled template. Thin wrapper around the canonical `lrvx new` CLI — the CLI stays the source of truth, this tool only makes it discoverable from MCP. Use when the user asks 'set up a new lrvx project' / 'I want to scaffold a research notebook' / 'start a live trading bot'. Three templates ship with lrvx: `research` (notebook + sample data + main.py), `live` (CCXT broker + dry-run safety harness), `indicator-library` (standalone indicator package with tests). Result includes the CLI output and a Next steps section with `docs_search` queries.
- **record_data** — Capture market data into a `.lrvx` tape. Wraps the canonical recording paths — for `mode=live` shells out to the `lrvx tape record` CLI; for `mode=historical` shells out to `scripts/backfill_to_tape.py` which uses ccxt's `fetch_ohlcv` / `fetch_trades`. Use this when the user asks to 'record some BTC data' / 'pull a month of klines for backtest' / 'tape the last hour of trades'. The result is a `.lrvx` directory drivable by `BacktestRunner.run_tape`.
- **run_backtest** — Run a Python lrvx strategy against a CSV dataset in a sandboxed subprocess (rlimits on CPU / memory / output size + a wall-clock timeout). Use this when the user asks 'try this strategy on my data' or 'does this code actually work'. Treat as MVP sandbox: it caps resources but does NOT isolate the filesystem or network — never aim it at untrusted code outside a developer's own machine. Returns the backtest stats dict as JSON plus any stdout the strategy printed.

Dispatch routing: the worker introspects the strategy class. If `on_bar` is overridden the dataset is dispatched as real `BarEvent`s through `run_bars` (CSV columns: ts,open,high,low,close,volume); otherwise the rows are synthesised into trades for `on_trade` via `run_csv`. A strategy that overrides neither hook fails loudly.
- **compute_indicator** — Run a single lrvx indicator over a list of floats and return the output. Use this to sanity-check an indicator's behaviour on a small price array BEFORE wiring it into a strategy — especially when the indicator has window / period / smoothing parameters whose effect isn't obvious from the name. Input is capped at 1 MiB. Requires the optional `lrvx` dependency.
- **price_amm_swap** — Price a DEX swap against an AMM pool, exact to the wei, through lrvx's integer curves. Use this to quote a fill or measure price impact on a constant-product (Uniswap v2), Raydium CP (Solana), or Uniswap v3 concentrated-liquidity pool from its on-chain state. Amounts are decimal strings (native wei / lamports), so 256-bit values are lossless. Requires the optional `lrvx` dependency.
- **route_amm_swap** — Best execution for a DEX swap across a set of AMM pools, exact to the wei. Give it the same notional and several venues (constant-product, Raydium CP, Uniswap v3) and it returns the venue that fills the most, the fill, and a per-venue comparison. Amounts are human 'NUMBER SYMBOL' strings (e.g. '50000 USDC'); each pool carries its token symbols and decimals, so directions are by symbol and a mis-routed swap raises instead of returning a quiet zero. Requires the optional `lrvx` dependency.
- **amm_price_impact** — The depth / slippage table for one AMM pool: the realized average price and price impact for each of a list of trade sizes, exact to the wei. Use this to reason about how large a trade a pool can absorb before quoting. Sizes are human 'NUMBER SYMBOL' strings. Requires the optional `lrvx` dependency.
- **replay_pool_tape** — Backtest a DEX position from a recorded pool history. Replays a list of swaps (or decoded Uniswap v2 Swap logs) through the exact curve and returns the price / reserves / LP-value / impermanent-loss / drift series over time. Use this to evaluate an LP position or a trading sequence against a real transcript. Requires the optional `lrvx` dependency.
- **suggest_indicator** — Recommend lrvx indicators for an English description of the user's intent ('trend filter', 'momentum oscillator', 'volatility band', 'mean revert', 'regime test'). Use this when the user describes what they want without naming an indicator — the tool maps phrasing to a ranked shortlist of real lrvx indicators. Pure keyword heuristic; no LLM call. Always confirm shape with `list_indicators` after picking one.
- **docs_search** — Top-k full-text search over the lrvx documentation (how-to guides, reference pages, tutorials, error codes, bindings overviews, explanations). Use this to ground answers about lrvx behavior, configuration, or APIs in the actual docs instead of relying on training data — call it whenever the user asks 'how do I X' / 'what does Y do' / 'where is Z documented'. The index is built from a strict allowlist; private tracker / strategy / author files are NEVER indexed.

Query syntax: plain word lists are AND-matched (every token must appear). Wrap a phrase in double quotes for exact match: `"walk forward"`. FTS5 operators (OR, NEAR, *, parens) pass through.

Canonical workflow queries (run these instead of guessing the canonical path from training data):
  • User wants to record market data → `docs_search('record tape')`. Covers live capture and the ccxt.fetch_ohlcv historical-backfill pattern.
  • User asks 'how should I structure a lrvx project' → `docs_search('project layout')`.
  • User mentions an exchange / live data → `docs_search('ccxt')`.
  • User wants to backtest a strategy on a recorded tape → `docs_search('backtest')`.
  • User mentions strategy traces, signals, or `.lrvxrun` → `docs_search('lrvxrun')`.
- **get_positions** — Read positions from a running lrvx engine via its runtime state snapshot. Use this when the user asks 'what's in my positions' / 'show me the BTC position' / 'is strategy X long or short'. Returns a JSON object {snapshot_age_ms, data:[{account, strategy, symbol_id, symbol_name, qty, avg_price, unrealized_pnl}, ...]}. Snapshot path is LRVX_RUNTIME_STATE env var or the passed `state_path`; the user app is responsible for writing the snapshot. When no engine has written a snapshot yet, returns {engine: 'not_running', data: [], hint: ...} instead of an error — that's a normal pre-engine state, not a problem to surface to the user. Read-only — never modifies state.
- **get_open_orders** — Read in-flight orders from the runtime state snapshot. Use this for 'what orders are pending' / 'do I have anything sitting on Bybit'. Optional substring filter matches against symbol_name or strategy. Returns the engine_not_running idle response when no snapshot is present yet (no error). Read-only.
- **get_pnl** — Read PnL totals plus per-strategy breakdown from the runtime state snapshot. Use this for 'what's my PnL' / 'how is strategy X doing today'. Returns realized + unrealized + fees per strategy. Returns the engine_not_running idle response when no snapshot is present yet (no error). Read-only.
- **get_kill_switch** — Read kill-switch state from the runtime state snapshot. Returns {active, reason, since_ns}. Use this for 'is trading halted' / 'why was the kill switch tripped'. When no engine has written a snapshot, returns the idle response with active=false (there is no live trading to halt). Read-only — to flip the switch use set_kill_switch.
- **place_order** — Place an order through the user's running lrvx engine. Talks HTTP to the local ControlServer the user app embeds; reads URL + bearer token from LRVX_CONTROL_URL and LRVX_CONTROL_TOKEN. Default dry_run=true; the server simulates acceptance without dispatching to the executor. live tier additionally requires an approve_token issued out of band by the operator. Use this for manual hedges or operator-driven order entry.
- **cancel_order** — Cancel one open order by id. Talks HTTP to the local ControlServer. Default dry_run=true. Useful for operator-driven cleanup or panic stop. account is required and gated the same way as place_order: paper scope may only target paper-prefixed accounts.
- **cancel_all** — Cancel every open order, optionally filtered by symbol. Default dry_run=true. The most common 'panic stop' primitive after set_kill_switch. account is required and gated the same way as place_order: paper scope may only target paper-prefixed accounts.
- **flatten_positions** — Close every open position with opposite-side market orders, optionally filtered by symbol. Default dry_run=true. Use for 'close everything' operator actions or end-of-day flatten. account is required and gated the same way as place_order: paper scope may only target paper-prefixed accounts, and rows the positions accessor tags with a different account are skipped.
- **set_kill_switch** — Set the engine's kill-switch state. active=true halts all trading; active=false resumes. Default dry_run=true; explicit dry_run=false applies the change. Use for emergency halt and for resuming after manual review. The kill switch is engine-level, not per-account, so only live scope may call this -- paper tokens are refused even with dry_run=false.
- **list_strategies** — List the strategies the running lrvx engine knows about, with name, status, and the symbols each one subscribes to. Read-only. Use when the user asks 'what's running' / 'which strategies are active'.
- **get_strategy_state** — Return one strategy's current state as a JSON dict — params, position view, last decisions. Read-only. Use when the user asks 'what does strategy X think right now' / 'show me state for ema-trend'.
- **get_indicator_values** — Return the live values of indicators inside a strategy. Optional name filter narrows to one indicator. Read-only. Use for 'what's the EMA reading' / 'is the RSI overbought now'.
- **get_event_log** — Query the engine event log (signals emitted, orders placed, fills received, risk checks). Filters AND-compose. Read-only. Use for 'what happened in the last 5 minutes' / 'show me all the signals from ema-trend'. Default limit 100.
- **explain_decision** — Walk an event's causal-parent chain back toward the root. Returns the chain in order from the requested event to its root. Use when the user asks 'why did this fill happen' / 'trace the cause of order 42' — the chain shows which signal produced the order, which event triggered the signal, etc.
- **replay_window** — Run a sandbox replay over a time window. The engine side decides what 'replay' means: typical setups use the bundled tape primitives to drive a SimulatedExecutor over a tape slice. Read-only (sandbox-only mutations). Use for 'replay the last hour' / 'rerun this period in sandbox'.
- **whatif** — Counterfactual replay: same as replay_window plus a strategy-name filter and required param_overrides. Use for 'what if EMA period was 50 instead of 21' / 'show me the PnL if I had used a wider stop'.
- **validate_strategy_no_lookahead** — Static-analysis check for the most common backtest bug: lookahead bias. Walks the strategy code's AST and flags negative .shift(N), forward-index arithmetic like df.iloc[i+1], open-upper slices inside per-bar callbacks, and attribute names that look future-dated (next_*, future_*, lookahead_*). Heuristic, not a proof — false negatives are possible. Run before trusting any backtest result.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "flox-mcp": {
    "command": "uvx",
    "args": ["lrvx-mcp"],
    "env": {
      "LRVX_RUNTIME_STATE": "",
      "LRVX_CONTROL_URL": "",
      "LRVX_CONTROL_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `LRVX_RUNTIME_STATE`, `LRVX_CONTROL_URL`, `LRVX_CONTROL_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What flox-foundation/flox-mcp MCP server does

flox-foundation/flox-mcp exposes reference and development tools for the lrvx trading systems framework. Its bundled data covers the C API, binding symbol maps, error pages, strategy examples, and a searchable documentation index. The server also provides indicator introspection, strategy templates, static validation, and a backtest entry point.

Most operations inspect packaged, read-only data. The server can execute indicator calculations and launch Python backtests, but these capabilities have different execution boundaries and should be treated accordingly.

## How it works

An MCP client starts the server locally as a child process and communicates with it through stdio. There is no public hosting layer or server-side network service. The package can be installed with pip, after which `lrvx-mcp init` writes an MCP configuration for the project. The generated configuration launches `lrvx-mcp serve`.

The reference tools read versioned snapshots and indexes packaged with the wheel. The C API lookup uses the committed ABI snapshot, while symbol and binding queries use an IR-derived map. Documentation search uses an FTS5 SQLite index built from selected documentation roots. Strategy scaffolds are checked before delivery: Python templates are parsed and validated, and Node templates pass `node --check`.

## Setup and configuration

Install the package with:

```bash
pip install lrvx-mcp
lrvx-mcp init
```

Restart the MCP client after initialization. The initializer can write a project configuration, target a global Claude configuration, print the merged configuration instead of writing it, or replace an existing entry with `--overwrite`.

For indicator calculation, install the optional lrvx dependency:

```bash
pip install "lrvx-mcp[lrvx]"
```

An engine simulation can provide control settings for additional runtime state tools. Start `lrvx engine sim`, then pass its URL and token to `lrvx-mcp init --overwrite` using `--engine-url` and `--token`. The resulting configuration can set `LRVX_RUNTIME_STATE`, `LRVX_CONTROL_URL`, and `LRVX_CONTROL_TOKEN`.

## Tools and capabilities

- Inspect indicators with `list_indicators`, calculate one with `compute_indicator`, or rank candidates with the keyword-based `suggest_indicator` tool.
- Search the C API and binding exports using `list_capi_functions` and `list_bindings`.
- Translate names across C, Python, Node, and Codon with `lookup_symbol`.
- Decode supported event structures or raw event dictionaries through `explain_event`.
- Find error explanations with `lookup_error_code` and search indexed documentation with `docs_search`.
- Retrieve language-filtered examples with `get_example`.
- Generate bar-driven, trade-driven, or hybrid Python and Node strategy starters using `scaffold_strategy`.
- Check Python strategy syntax, required hooks, and forbidden `eval` or `exec` calls with `validate_strategy`.
- Run a Python strategy against CSV data with `run_backtest`, using CPU, memory, output, and wall-clock limits.

## Limitations and notes

The backtest subprocess is an MVP sandbox. It limits resources but does not isolate filesystem or network access, so production use with untrusted Python should add nsjail, firejail, Docker, or an equivalent isolation layer. `suggest_indicator` uses keyword matching rather than an LLM and its result should be checked with `list_indicators`. The server’s local stdio design keeps requests on the machine, but it does not by itself provide stronger isolation for code execution.

_Full upstream README: https://allmcps.com/mcp/flox-foundation-flox-mcp/readme_