# 🧪 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. -->
![Litmus auditing a flawed strategy](docs/demo.png)

---

## 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](https://gofastmcp.com), 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](https://docs.astral.sh/uv/) (recommended):

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

Or with pip:

```bash
pip install -r requirements.txt
```

### Try it with no LLM

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) calls your tools directly, so you can test everything before wiring up a model:

```bash
fastmcp dev server.py
```

### Connect to Claude Desktop

```bash
fastmcp install server.py
```

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

```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