Skip to main content
Glama
backtest360-mcp

backtest360-mcp

Official
by Backtest360

backtest360-mcp

PyPI version Python versions License: MIT tests

MCP server exposing the Backtest360 engine API as tools for AI agents.

Connect any MCP-capable AI client and drive real backtests conversationally: discover indicators, build and validate strategies, run backtests, and read the results — all against the deterministic Backtest360 engine. The server contains no AI and computes no numbers of its own; it is a thin, faithful adapter over the engine HTTP API. Your engine API key and its plan govern everything (permissions, rate limits, data access).

Two transports: a hosted HTTP endpoint at https://mcp.backtest360.com/mcp (send your key as an X-API-Key header) and local stdio (self-host — see below).

Install

pip install backtest360-mcp        # or, from a clone: pip install -e .

Requires Python 3.10+ and a Backtest360 API key. Get one free, instantly at backtest360.com/api-access — submit your email and a key (format b360_…) is issued on the spot and emailed to you; no approval needed. Authentication is API-key only. The free tier runs backtests on data you upload; fetching historical price data from the engine server-side is a paid capability.

Related MCP server: FinClaw

Configuration

Everything is environment-driven:

Variable

Required

Default

Purpose

BACKTEST360_API_KEY

yes

—

Engine API key, sent as X-API-Key

BACKTEST360_ENGINE_URL

no

https://api.backtest360.com

Engine base URL

BACKTEST360_MCP_TIMEOUT

no

300

Per-request timeout (seconds)

BACKTEST360_MCP_MAX_OUTPUT_BYTES

no

100000

Hard cap on a single tool result

Connect an MCP client

Point your MCP client at the hosted endpoint over HTTP and send your key as an X-API-Key header:

{
  "mcpServers": {
    "backtest360": {
      "type": "streamable-http",
      "url": "https://mcp.backtest360.com/mcp",
      "headers": {
        "X-API-Key": "b360_..."
      }
    }
  }
}

Local (stdio)

Run the server yourself and let your client launch it over stdio (the common mcpServers shape):

{
  "mcpServers": {
    "backtest360": {
      "command": "backtest360-mcp",
      "env": {
        "BACKTEST360_API_KEY": "b360_..."
      }
    }
  }
}

Prefer not to put the key in a config file? Point command at a small wrapper script that exports the key from your secrets manager and then runs backtest360-mcp. A minimal example config is in examples/mcp.json.

Tools

Tool

What it does

engine_info

Engine version, API contract, health

get_me

What the configured key can do: permission scopes, limits, current usage, capability flags

get_catalog

Reference catalogs: operators, execution modes, stop types, sizing methods, bar frequencies, metric sections

list_indicators

Indicator discovery; per-indicator parameter schemas

list_templates

Predesigned strategy templates — discover compactly, fetch one in full, ready to validate and run

get_strategy_schema

JSON Schema for strategy documents

validate_strategy

Validate a strategy without running it — returns structured, locatable errors

run_backtest

Run a historical backtest

get_latest_signal

Evaluate the most recent bar only (no P&L)

compare_backtests

Run several strategies on the same data, side by side

compute_stats

Compute the metric set from an externally produced returns series

search_tickers / list_tickers

Asset discovery for server-side data fetch

get_data_range

Available history and bar-count estimate for a symbol

get_ticker_info

Symbol identity and data coverage in a single call

get_quote

Latest available price for a symbol (paid plan)

get_price_history

OHLCV price history over a date range (paid plan; long histories downsampled to fit)

list_macro_series / get_macro_series

Macroeconomic data: list the series catalog, then fetch one series' observations

The cheap static catalogs are also published as MCP resources (backtest360://catalog/{name}, backtest360://schema/strategy) for clients that support resource attachment.

Prompts

Two workflow prompts scaffold the common multi-tool flows for a connected AI: each names which tools to call, in what order, and what to look at in the results. They carry no interpretation and compute nothing — the connected AI does the reasoning.

Prompt

Arguments

What it scaffolds

robustness_review

symbol, strategy (optional)

Review a backtested strategy for robustness: validate → run → compare against buy-and-hold → weigh the evidence base (sample size, significance/robustness statistics, warnings) → caveated summary

build_and_validate

idea

Turn a plain-language idea into a validated strategy: survey the catalogs → fetch the schema → construct → validate-and-fix loop → dry-run

Response shaping

A full backtest result is megabytes; an agent's context is not. run_backtest and compare_backtests take response_detail:

  • summary (default) — headline metrics, warnings, counts, equity endpoints

  • stats — every metric the plan allows

  • full — plus series (downsampled, endpoints preserved) and trades (paginated)

run_backtest also takes max_series_points (default 500, must be >= 2) to override the series downsampling cap — set it higher for full-resolution series on a long run, or leave it unset for today's default.

include=["trades", "equity_curve", "monthly_returns", "yearly_returns", "signal_diagnostics"] adds specific blocks at any detail level. signal_diagnostics reports which per-bar entry/exit conditions fired, as a capped list of fire dates per condition (not the raw per-bar boolean arrays, which downsampling would corrupt) — or {"available": false, ...} when the run has no condition tree to evaluate (e.g. precomputed signals). Results exceeding the output cap are reduced further and explicitly marked truncated_by_mcp — never silently cut. Shaping only ever selects and thins what the engine returned; no value is computed or altered.

Error semantics

Designed for agents:

  • Fixable by changing the request → returned as a normal result: failed validations arrive as {"valid": false, "errors": [...]} with machine codes and document locations; engine rejections arrive as {"accepted": false, "error": ...} with a hint.

  • Not fixable that way → a tool error with explicit guidance: rate limits carry the Retry-After value; engine-busy says retry with backoff; a compute timeout says do not retry and reduce scope instead; permission problems name the missing capability. Engine request ids are included for support.

Running the tests (self-host)

pip install -e ".[dev]"
pytest   # unit suite vs a mock engine — no network

Questions / feedback

Questions or feedback? hello@backtest360.com — we read everything. backtest360-mcp is in active development, so help shape it.

Bug reports and feature requests: open an issue on GitHub.

License

MIT — see LICENSE.

Available Tools

14 tools
compare_backtestsAInspect

Run several strategies on the same data and compare side by side.

One quota-counted call, but compute scales with the number of strategies. The engine enforces a wall-clock budget for the whole comparison; when it runs out mid-way the response carries "truncated": true and the remaining strategies are missing — report that to the user rather than re-running blindly.

Args: data_source: Shared data source (same shape as run_backtest). strategies: List of {"label": str, "strategy": {...}, "execution": {...}?} entries. include_benchmark: Add a buy-and-hold benchmark to the comparison. response_detail: Shaping level applied to each strategy's result. trades_limit: Max trades per strategy when detail is 'full'.

Returns: {"strategies": [{"label", "result"}, ...], "equity_curves": {...}}, each result shaped at the requested detail. Two truncation flags are distinct and may both appear: the engine's "truncated" (wall-clock budget exhausted mid-comparison — strategies are missing) and the MCP size-cap marker "truncated_by_mcp". A 400/422 rejection returns {"accepted": false, "error": ...}; capacity/timeout/permission failures raise a tool error.

Inputs: strategies (required), data_source (required), trades_limit, response_detail, +1 more. Returns: object

compute_statsAInspect

Compute the engine's performance metrics from a returns series.

Use when the returns came from somewhere other than run_backtest (an external system, a portfolio) — backtest results already include these statistics.

Args: returns: Per-bar log returns as {"dates": [...], "values": [...]} parallel arrays (ISO-8601 dates). trading_days_per_year: Required annualization factor — 252 for a daily equities calendar, 365 for 24/7 crypto. Must match the bar calendar of the returns series; a wrong value silently mis-annualizes Sharpe, volatility, and CAGR. benchmark_returns: Optional benchmark series, same shape — adds alpha/beta/capture metrics. trades: Optional trade records (entry_date, exit_date, direction, return_net, ...) — adds trade-level metrics. risk_free_rate: Annual risk-free rate as a decimal.

Returns: {"stats": {...}} — the metric set the API key's plan allows. See get_catalog('sections') for every metric's id and description.

Inputs: returns (required), trading_days_per_year (required), trades, risk_free_rate, +1 more. Returns: object

engine_infoAInspect

Engine version, API contract number, and health.

Free (not quota-counted). Call once at the start of a session to confirm the engine is reachable and which contract it serves.

Inputs: no named parameters. Returns: object

get_catalogAInspect

Fetch one engine reference catalog.

Catalogs (cheap, cacheable per session):

  • 'operators' — comparison operators for condition expressions

  • 'execution-modes' — entry/exit anchors and fill algorithms, with the validity matrix by market type

  • 'stop-types' — stop-loss types, re-entry modes, and their parameters

  • 'sizing-methods' — position-sizing methods and their parameters

  • 'bar-frequencies' — supported bar frequencies and the signal x execution validity matrix (which combinations are allowed)

  • 'sections' — the full metric catalog: every statistic's stable id, display label, section, and description

Fetch the relevant catalog BEFORE building a strategy or config; build only from values it lists — never guess parameter names or frequencies.

Inputs: catalog (required). Returns: object

get_data_rangeAInspect

Available date range and estimated bar count for a symbol/frequency.

Available on paid plans. Call before a server-side fetch so the requested start/end stay inside what the provider can deliver and the bar count stays inside the key's per-run limit.

Inputs: symbol (required), frequency (required). Returns: object

get_latest_signalAInspect

Evaluate the strategy on the most recent bar only — no P&L, no stats.

Returns the latest signal (-1/0/1), which condition slots fired, and the bar timestamp. Use for "what would this strategy do right now" questions; use run_backtest for performance.

Inputs: strategy (required), data_source (required), execution, data_inputs. Returns: object

get_meAInspect

The configured API key's permissions, limits, and current usage.

Cheap. Call early in a session — before planning work — to learn what this key can do instead of discovering limits through failed calls.

Returns: scopes: the permission scopes the key carries. limits: requests per minute and per day, max concurrent requests, and the per-run bar cap (null when uncapped). usage: current consumption against those limits, with reset countdowns in seconds. capabilities: feature flags such as server-side data fetch and the full metric set. A small fixed-shape record, returned as the engine sent it.

Inputs: no named parameters. Returns: object

get_strategy_schemaAInspect

JSON Schema for the strategy document (condition_tree + indicators).

Fetch this before composing a strategy by hand; the validate_strategy tool checks against the same rules.

Inputs: no named parameters. Returns: object

list_indicatorsAInspect

List indicators, or fetch one indicator's full schema.

Cheap, cacheable per session.

With no arguments: a compact catalog — {"indicators": [...], "count": N} — where each entry carries id, name, category, kind, and value_dtype (no description, to keep the discovery scan small). Use it to discover what exists. Pass name='rsi' (id or name, case-insensitive) to get that single indicator's complete entry including its description and params_schema — do this before adding an indicator to a strategy so its parameters are exactly right. Pass compact=False for full entries for everything (large; the MCP server may cap it and set truncated_by_mcp — prefer compact or name=).

Wire optimization: the compact discovery path asks the engine to omit per-entry descriptions (descriptions=false) since they are stripped locally anyway; the name= and compact=False paths request them. This is a pure saving — if the engine ignores the param it returns full entries and the local compact strip still yields a lean result.

Inputs: name, compact.

list_templatesAInspect

List predesigned strategy templates, or fetch one in full.

Cheap, cacheable per session. The engine returns the templates available to the calling key.

With no arguments: a compact catalog — {"templates": [...], "count": N} — where each entry carries id, origin, name, and description. Use it to discover what exists. Pass name='sma-cross' (id or name, case-insensitive) to get that single template's complete entry: its strategy logic (condition_tree + indicators, the same shape validate_strategy and run_backtest accept) plus parameter metadata — defaults (starting parameter values), requires, and locked_params (parameters that must keep their template values). Pass compact=False for complete entries for everything (large; the MCP server may cap it and set truncated_by_mcp — prefer compact or name=).

Inputs: name, compact.

list_tickersAInspect

List available tickers, optionally filtered by asset class.

The full universe is very large, so the MCP server caps the returned list and marks it truncated_by_mcp — pass asset_class to narrow it, or use search_tickers to resolve a specific asset by name.

Inputs: asset_class. Returns: object

run_backtestAInspect

Run a historical backtest against the engine.

Quota-counted and compute-bound. Validate the strategy first (validate_strategy is far cheaper). On a 504 compute timeout, do NOT retry the same request — reduce the date range, use a coarser frequency, or simplify the strategy. On 429/503, wait for the advertised Retry-After before retrying.

Args: data_source: Either inline OHLCV ({"ohlcv": {dates, open, high, low, close, volume?}} as parallel arrays, ISO-8601 dates) or a server-side fetch ({"symbol", "start", "end", "frequency"} — requires a paid plan). strategy: Strategy document (indicators[] + condition_tree). Mutually exclusive with signals. signals: Precomputed signal series ({"dates": [...], "values": [-1|0|1, ...]}). Mutually exclusive with strategy. execution: Execution/cost/risk/sizing settings. Use values from get_catalog('execution-modes'/'stop-types'/'sizing-methods'); omit for engine defaults. benchmark: Optional benchmark data source (same shape as data_source) — adds benchmark-relative metrics. data_inputs: Optional custom time-series the strategy references (name -> {dates, values}). response_detail: 'summary' (default — headline metrics, smallest), 'stats' (every metric), 'full' (plus trades and series downsampled to a fixed, server-controlled number of points). include: Optional add-on blocks at summary/stats detail: 'trades', 'equity_curve', 'monthly_returns', 'yearly_returns'. trades_limit: Max trades returned when trades are included.

Returns: The shaped result at the requested detail; an oversized result is thinned and marked truncated_by_mcp. If the engine rejects the request as invalid (400/422), returns {"accepted": false, "error": ...} so you can fix the named field(s) and retry. Capacity, timeout, and permission failures (e.g. 429/503/504/401/403) raise a tool error carrying explicit recovery guidance.

Inputs: data_source (required), include, signals, strategy, +5 more. Returns: object

search_tickersAInspect

Search available assets by ticker or name (relevance-ranked).

Use to resolve a user's asset mention ("bitcoin", "S&P") to the exact ticker before requesting a server-side data fetch. asset_class filters to 'stocks', 'crypto', 'forex', or 'indices'.

Inputs: query (required), limit, asset_class. Returns: object

validate_strategyAInspect

Validate a strategy document without running a backtest.

A cheap quota separate from backtest runs, so validate freely and ALWAYS before run_backtest.

Args: strategy: The strategy document — name, indicators[], and condition_tree (see get_strategy_schema for the exact shape). injected_indicators: Names of custom time-series columns the caller will supply via data_inputs at run time, so conditions referencing them validate.

Returns: On success: {"valid": true, "warmup_bars": ..., referenced indicators/columns}. On failure: {"valid": false, "errors": [...]} where each error carries a machine code, the location in the document, a message, and context (e.g. the list of valid column names). A failed validation is a NORMAL result, not an error — read the errors, fix the document, and validate again before running.

Inputs: strategy (required), injected_indicators. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: validation, backtest execution, comparison, statistics, catalog browsing, ticker search, etc. Overlaps are minimal and clearly differentiated (e.g., get_latest_signal returns current signal only, run_backtest returns full performance).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., validate_strategy, run_backtest, list_indicators). No mixing of conventions like camelCase or inconsistent verb styles.

    Tool Count5/5

    14 tools is well within the 3-15 ideal range. Each tool serves a necessary function for the backtesting domain—validation, execution, analysis, discovery—without bloat or missing essentials.

    Completeness4/5

    Covers the core backtesting workflow: strategy creation (schema, validation), execution (run, compare, signal), data discovery (tickers, range), and analysis (stats). Minor gaps: no tool for editing saved strategies or managing user settings, but these are peripheral to the server's main purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      An MCP server that exposes the Jesse algorithmic trading framework's capabilities to LLM agents for backtesting, optimization, and risk analysis. It provides 32 specialized tools for managing trading strategies and performing comprehensive market simulations via the Jesse REST API.
      69
      23
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides AI agents with financial tools including real-time quotes, backtesting, technical analysis, and multi-exchange data via a simple CLI interface.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call.
      5
      MIT