@rulyfi/mcp

An MCP server that gives AI agents (Claude Code, Claude Desktop, Cursor, and any MCP client) access to the Rulyfi backtest API — validate a strategy, backtest it on real market data, and scan a whole parameter neighborhood to tell a real edge from an overfit one.

The point isn't just "run a backtest." It's honest statistics: every backtest returns the Probabilistic Sharpe Ratio (PSR), and every scan returns DSR (deflated Sharpe ratio), RMP (Random-Max Percentile — the probability that the best result pure chance would produce across the scan's num_trials falls below this row; exploratory, and it stays informative at high trade counts where DSR saturates) and num_trials across the full evaluated population — so a strategy that only looks good because it was cherry-picked from thousands of trials is exposed. Your AI can generate strategies all day; our statistics don't flatter them.

Great for porting a strategy: have an agent translate your Python/TradingView strategy into the Rulyfi format, use validate_strategy to fix it error-by-error, then run_backtest to check it.

The backtest engine runs entirely on Rulyfi's servers. This package is a thin API client + candle-fetch orchestrator — it contains no strategy engine and no WASM.

Install

You need a Rulyfi API key. Create one on your account page: rulyfi.com → Account → API keys (requires a paid plan — Plus or higher). Keys look like rk_live_… and are shown once.

Claude Code

claude mcp add rulyfi --env RULYFI_API_KEY=rk_live_your_key -- npx -y @rulyfi/mcp

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "rulyfi": {
      "command": "npx",
      "args": ["-y", "@rulyfi/mcp"],
      "env": { "RULYFI_API_KEY": "rk_live_your_key" }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "rulyfi": {
      "command": "npx",
      "args": ["-y", "@rulyfi/mcp"],
      "env": { "RULYFI_API_KEY": "rk_live_your_key" }
    }
  }
}

Environment

| Variable | Required | Description | |---|---|---| | RULYFI_API_KEY | yes | Your rk_live_… key. | | RULYFI_API_URL | no | Override the API base URL (advanced; defaults to the production /v1 base). |

Tools

| Tool | What it does | |---|---| | list_indicators | The full indicator catalog (103 indicators): types, parameters, outputs, descriptions, operators, price fields. | | list_symbols | Supported exchanges (26), timeframes, and directions. | | validate_strategy | Validate a strategy and return every error with a field path and a correct example — the porting/correction loop. | | run_backtest | Backtest one spot symbol over a date range. Returns return %, win rate, Sharpe, max drawdown, profit factor, exit breakdown, and PSR. Fetches candles, uploads them, and runs — all in one call. | | run_scan | Scan a parameter neighborhood (a grid across indicator combos) as one paid job; every result carries DSR and num_trials to judge overfitting. | | get_scan_results | Fetch a scan's status and top-K leaderboard (with PSR/DSR/num_trials/walk-forward). | | download_export | Stream a scan's full-population parquet export to your local disk (./rulyfi-exports/{scan_id}/) for analysis in duckdb/pandas. |

Pricing

Backtesting uses your Rulyfi credits at the same rate as the scanner: 1,000 API backtest calls = 1 credit (billed as a prepaid 1,000-call block, so normal use of tens or hundreds of calls per session is effectively free). Scans are billed by the size of the parameter grid, exactly like the web scanner. Lane 1 backtests are spot-market only. Per-key rate and daily-call limits apply; when you hit them, the error nudges you toward run_scan, which tests a whole parameter grid far more cheaply than thousands of single backtests. Re-running an identical scan is served from cache for free — but cached runs produce no parquet export, so pass force_fresh: true when you need the full export (recomputes and re-charges credits).

Notes

• Candles are fetched locally on your machine (cached under ~/.rulyfi-mcp/candles/) and uploaded once per range, then referenced by candle_ref — repeat backtests on the same data don't re-fetch.
• Strategy format reference: https://rulyfi.com/strategy-schema.md.