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
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-*.whlThe server. In Claude Code, the plugin (server and skill):
claude plugin marketplace add reamerlabs/reamer-research-mcp claude plugin install reamer-research@reamerlabsThe server alone, in Claude Code:
claude mcp add reamer-research -- uvx reamer-research-mcpIn Claude Desktop, Cursor and other clients:
{ "mcpServers": { "reamer-research": { "command": "uvx", "args": ["reamer-research-mcp"] } } }Without uv, run
pip install reamer-research-mcpand usereamer-research-mcpas 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:
REAMER_PYTHON, if set: the path of that Python, for example~/venv/bin/python.- The Python running the server.
python3, thenpython, onPATH.
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.