All docs pages

Docs · Getting started

MCP server and Claude Code plugin

Adapted from github.com/reamerlabs/reamer-research-mcp in the 4.11.3 Reamer Research kit.

The Reamer Research MCP server connects an AI assistant to the Reamer Research engine installed on your machine, over the Model Context Protocol (stdio). It is MIT licensed, on PyPI as reamer-research-mcp, and listed in the official MCP Registry as io.github.reamerlabs/reamer-research-mcp. The same repository is a Claude Code plugin marketplace whose reamer-research plugin installs the server and a Reamer Research skill.

Install

  1. The engine. Download the kit from the download page and install its wheel:

    tar xzf research-kit-*.tar.gz
    pip install research-kit-*/python/reamer_research-*.whl
    
  2. The server. In Claude Code, the plugin (server and skill):

    claude plugin marketplace add reamerlabs/reamer-research-mcp
    claude plugin install reamer-research@reamerlabs
    

    The server alone, in Claude Code:

    claude mcp add reamer-research -- uvx reamer-research-mcp
    

    In Claude Desktop, Cursor and other clients:

    {
      "mcpServers": {
        "reamer-research": { "command": "uvx", "args": ["reamer-research-mcp"] }
      }
    }
    

    Without uv, run pip install reamer-research-mcp and use reamer-research-mcp as the command.

The server needs Python 3.10 or later. The engine runs on Python 3.9 or later, in the same environment or another one.

Finding the engine

The server looks for a Python that imports reamer_research, in this order:

  1. REAMER_PYTHON, if set: the path of that Python, for example ~/venv/bin/python.
  2. The Python running the server.
  3. python3, then python, on PATH.

engine_status reports which one it found. In a client config, set the variable under env:

"env": { "REAMER_PYTHON": "/home/you/venv/bin/python" }

Tools

Tool Arguments Returns
engine_status none Engine version, its Python, default settings, Evaluation Mode limits, the runs directory; or install steps.
api_reference topic: strategy, data, orders, settings, data_files, results, evaluation_mode, live, install, or none for all The strategy API in Markdown.
backtest strategy_file, data, and optional strategy_name, lookback, start, end, settings, ticker_config, timeout_s (600) run_id, the summary metrics, the last lines printed, and the paths of the report and the trade diagnostics page.
closed_trades run_id, sort_by (close_timestamp), descending, ticker, limit (50, at most 500), offset The run's closed trades, sorted and paged.
monte_carlo run_id, simulations (10000), seed (0) Loss, ruin and drawdown statistics from resampled per-trade returns.
printed_output run_id, limit (200), offset What the strategy printed, one JSON line per print with its bar's time.
open_trade_diagnostics run_id, open_browser (true) The path of the run's trade diagnostics page, opened in the browser.

strategy_file is a Python file that defines an on_bar function, a class with on_bar, or an object with one, as in the Python package. When it defines several, pass strategy_name. data is a .csv or .bin path, a list of paths, or {ticker: path}; relative paths resolve against the directory the client starts the server in, and absolute paths always work. settings takes any key of rr.DEFAULTS, such as commission_per_unit, spread, slippage, initial_capital and rng_seed, as defined in the execution specification. Every cost defaults to zero.

monte_carlo reruns the stored backtest, which gives the same trades to the byte, then resamples them.

Runs

Each backtest runs in its own process under the engine's Python, with the strategy file's directory as its working directory. Everything the strategy prints is stored with the run, so it never reaches the MCP connection. Each run directory holds:

File Contents
spec.json The arguments the run was given.
report.json The full result document, as in the result JSON schema.
console.jsonl Every print, stamped with its bar's time.
trade-diagnostics.html The run in visual trade diagnostics.
outcome.json The summary or the error.

Runs are stored in ~/.cache/reamer-research-mcp/runs/ (under $XDG_CACHE_HOME when set). REAMER_MCP_RUNS moves them. Delete old runs whenever you like.

Errors

A failed run returns ok: false with error_type and error:

error_type Meaning
EngineNotFound No Python with reamer_research was found; the message gives the install steps.
EvaluationLimit The run is past an Evaluation Mode limit, which the message names.
FileNotFoundError The strategy or data path does not exist.
Timeout The run passed timeout_s and was stopped.
Any other An exception from the strategy or the engine, with a traceback.

Evaluation Mode

Without a licence, each backtest runs on one ticker over at most 30 days or 50,000 bars, and live trading is off. Every tool works within those limits. A licence removes them, and the same strategy files run unchanged.

The skill

The plugin's reamer-research skill gives Claude Code the workflow (check the engine, read the API, write the strategy, backtest with your costs, report the summary, inspect the trades) and the engine's rules. It loads when you ask to backtest or port a strategy, and works from a plain script when the server is not connected.

Buy a licenceKey and kit by email on payment.