🧪 Litmus

An MCP server that lets an AI agent backtest, risk-check, and audit trading strategies — the litmus test for whether your edge is real.

Point Claude (or Cursor, or any MCP client) at Litmus and ask: "Is this Freqtrade strategy overfit, or does it actually work?" — and get a real answer, backed by a backtest, a walk-forward analysis, and a static audit of the code. The model does the talking; Litmus does the maths.

<!-- Replace with a real screen recording: Claude calling audit_strategy on a broken strategy and getting a FAIL verdict. The GIF is the pitch — record it before launch. -->

---

Why

Most trading tools help you build strategies. Litmus exists to tell you the truth about them. A backtest is easy to fake without realising it — a stop-loss that never triggers, a feature that peeks at the next candle, a "high-frequency" idea that a polling framework can't actually run. Litmus catches those before they cost you money, and it does it from inside the AI agent you're already chatting with.

It's built on FastMCP, the standard framework for MCP servers. The server is free and open source; you only ever pay for your own model usage, because the inference runs in your client, not here.

Tools

Tool	What it does
fetch_ohlcv	Pull historical candles from any exchange via ccxt. Returns a dataset_id the other tools reuse.
backtest_strategy	Backtest a built-in strategy net of fees and slippage. Returns net return vs buy & hold, Sharpe, drawdown, win rate, profit factor, expectancy.
walk_forward	Optimise in-sample, measure out-of-sample, fold by fold. A big gap = overfit, not profitable. Returns a plain-language verdict.
risk_metrics	Sharpe, Sortino, volatility, max drawdown, Calmar, VaR & CVaR (95% / 99%) from an equity curve or returns.
monte_carlo	Project the range of futures a strategy implies (Box-Muller), with probability of loss and projected drawdowns.
audit_strategy	The differentiator. Statically audits Freqtrade-style code for lookahead bias, cosmetic stop-losses, impossible timeframes, missing informative_pairs(), and oversized hyperopt surfaces. The code is parsed, never run.

Install

Requires Python 3.10+. Using uv (recommended):

git clone https://github.com/Spectrexf/litmus-mcp.git
cd litmus-mcp
uv venv && uv pip install -r requirements.txt

Or with pip:

pip install -r requirements.txt

Try it with no LLM

The MCP Inspector calls your tools directly, so you can test everything before wiring up a model:

fastmcp dev server.py

Connect to Claude Desktop

fastmcp install server.py

That patches your Claude Desktop config automatically. To do it by hand instead, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "litmus": {
      "command": "python",
      "args": ["/absolute/path/to/litmus-mcp/server.py"]
    }
  }
}

Restart Claude Desktop and Litmus's tools appear.

Example prompts

Once connected, just talk to your agent:

• "Audit this strategy for me" → paste a Freqtrade strategy, Litmus runs audit_strategy and returns a PASS/WARN/FAIL verdict with line numbers.
• "Backtest a 20/50 moving-average cross on BTC/USDT daily and tell me if it beats buy and hold after costs."
• "Is this strategy overfit?" → Litmus runs walk_forward and reports in-sample vs out-of-sample.
• "Run a Monte Carlo on these returns — what's my probability of a losing year?"

See the audit catch real flaws

examples/flawed_strategy.py is a deliberately broken strategy. Feed its contents to audit_strategy and Litmus reports four blocking issues and two warnings: a sub-minute timeframe, a cosmetic stoploss = -0.99, two kinds of lookahead bias, a missing informative_pairs(), and a 10-parameter hyperopt surface.

Built-in strategies

So the agent can backtest without you writing a strategy class:

• ma_cross — moving-average crossover. Params: fast, slow.
• rsi_reversion — buy oversold, exit overbought. Params: period, lower, upper.
• breakout — enter on N-bar high breakout. Params: lookback.

How it works

Plain Python, organised into small engine classes that the MCP tools delegate to:

server.py        FastMCP app — the 6 tools
market_data.py   MarketData    — ccxt wrapper (lazy-imported)
backtester.py    Backtester    — vectorised backtest + walk-forward, costs included
risk.py          RiskAnalyzer  — metrics + Monte Carlo (Box-Muller)
auditor.py       StrategyAuditor — AST-based static analysis

Fetched candles are cached server-side and referenced by dataset_id, so a 500-candle series never has to travel through the model's context twice.

Roadmap

• [ ] Config auditor: catch shared-SQLite-DB collisions and other multi-bot Freqtrade footguns
• [ ] More lookahead patterns (resampling leaks, .iloc[-1] misuse)
• [ ] Custom strategy upload, not just built-ins
• [ ] Equity-curve charts rendered inline via MCP Apps
• [ ] Expose a strategy library as MCP resources

Contributing

Issues and PRs welcome — especially new audit rules. If you've been burned by a backtest that lied, encode the lesson here.

License

MIT © Adrián Llaca Mayo