{
  "markdown": "# backtest360-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/backtest360-mcp.svg)](https://pypi.org/project/backtest360-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/backtest360-mcp.svg)](https://pypi.org/project/backtest360-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![tests](https://github.com/Backtest360/backtest360-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Backtest360/backtest360-mcp/actions/workflows/test.yml)\n\nMCP server exposing the [Backtest360](https://backtest360.com) engine API as tools for AI agents.\n\n<!-- mcp-name: com.backtest360/backtest360 -->\n\nConnect any MCP-capable AI client and drive real backtests conversationally: discover\nindicators, build and validate strategies, run backtests, and read the results — all\nagainst the deterministic Backtest360 engine. The server contains no AI and computes no\nnumbers of its own; it is a thin, faithful adapter over the engine HTTP API. Your engine\nAPI key and its plan govern everything (permissions, rate limits, data access).\n\nTwo transports: a **hosted HTTP endpoint** at\n`https://mcp.backtest360.com/mcp` (send your key as an `X-API-Key` header) and **local\nstdio** (self-host — see below).\n\n## Install\n\n```bash\npip install backtest360-mcp        # or, from a clone: pip install -e .\n```\n\nRequires Python 3.10+ and a Backtest360 API key. Get one **free, instantly** at\n[backtest360.com/api-access](https://backtest360.com/api-access) — submit your email and a key\n(format `b360_…`) is issued on the spot and emailed to you; no approval needed. Authentication\nis **API-key only**. The free tier runs backtests on data you upload; fetching historical price\ndata from the engine server-side is a paid capability.\n\n## Configuration\n\nEverything is environment-driven:\n\n| Variable | Required | Default | Purpose |\n|---|---|---|---|\n| `BACKTEST360_API_KEY` | yes | — | Engine API key, sent as `X-API-Key` |\n| `BACKTEST360_ENGINE_URL` | no | `https://api.backtest360.com` | Engine base URL |\n| `BACKTEST360_MCP_TIMEOUT` | no | `300` | Per-request timeout (seconds) |\n| `BACKTEST360_MCP_MAX_OUTPUT_BYTES` | no | `100000` | Hard cap on a single tool result |\n\n## Connect an MCP client\n\n### Hosted (recommended)\n\nPoint your MCP client at the hosted endpoint over HTTP and send your key as an\n`X-API-Key` header:\n\n```json\n{\n  \"mcpServers\": {\n    \"backtest360\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://mcp.backtest360.com/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"b360_...\"\n      }\n    }\n  }\n}\n```\n\n### Local (stdio)\n\nRun the server yourself and let your client launch it over stdio (the common\n`mcpServers` shape):\n\n```json\n{\n  \"mcpServers\": {\n    \"backtest360\": {\n      \"command\": \"backtest360-mcp\",\n      \"env\": {\n        \"BACKTEST360_API_KEY\": \"b360_...\"\n      }\n    }\n  }\n}\n```\n\nPrefer not to put the key in a config file? Point `command` at a small wrapper script\nthat exports the key from your secrets manager and then runs `backtest360-mcp`. A\nminimal example config is in [`examples/mcp.json`](examples/mcp.json).\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `engine_info` | Engine version, API contract, health |\n| `get_me` | What the configured key can do: permission scopes, limits, current usage, capability flags |\n| `get_catalog` | Reference catalogs: operators, execution modes, stop types, sizing methods, bar frequencies, metric sections |\n| `list_indicators` | Indicator discovery; per-indicator parameter schemas |\n| `list_templates` | Predesigned strategy templates — discover compactly, fetch one in full, ready to validate and run |\n| `get_strategy_schema` | JSON Schema for strategy documents |\n| `validate_strategy` | Validate a strategy without running it — returns structured, locatable errors |\n| `run_backtest` | Run a historical backtest |\n| `get_latest_signal` | Evaluate the most recent bar only (no P&L) |\n| `compare_backtests` | Run several strategies on the same data, side by side |\n| `compute_stats` | Compute the metric set from an externally produced returns series |\n| `search_tickers` / `list_tickers` | Asset discovery for server-side data fetch |\n| `get_data_range` | Available history and bar-count estimate for a symbol |\n| `get_ticker_info` | Symbol identity and data coverage in a single call |\n| `get_quote` | Latest available price for a symbol (paid plan) |\n| `get_price_history` | OHLCV price history over a date range (paid plan; long histories downsampled to fit) |\n| `list_macro_series` / `get_macro_series` | Macroeconomic data: list the series catalog, then fetch one series' observations |\n\nThe cheap static catalogs are also published as MCP resources\n(`backtest360://catalog/{name}`, `backtest360://schema/strategy`) for clients that\nsupport resource attachment.\n\n## Prompts\n\nTwo workflow prompts scaffold the common multi-tool flows for a connected AI: each\nnames which tools to call, in what order, and what to look at in the results. They\ncarry no interpretation and compute nothing — the connected AI does the reasoning.\n\n| Prompt | Arguments | What it scaffolds |\n|---|---|---|\n| `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 |\n| `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 |\n\n## Response shaping\n\nA full backtest result is megabytes; an agent's context is not. `run_backtest` and\n`compare_backtests` take `response_detail`:\n\n- `summary` (default) — headline metrics, warnings, counts, equity endpoints\n- `stats` — every metric the plan allows\n- `full` — plus series (downsampled, endpoints preserved) and trades (paginated)\n\n`run_backtest` also takes `max_series_points` (default 500, must be >= 2) to\noverride the series downsampling cap — set it higher for full-resolution\nseries on a long run, or leave it unset for today's default.\n\n`include=[\"trades\", \"equity_curve\", \"monthly_returns\", \"yearly_returns\",\n\"signal_diagnostics\"]` adds specific blocks at any detail level.\n`signal_diagnostics` reports which per-bar entry/exit conditions fired, as a\ncapped list of fire dates per condition (not the raw per-bar boolean arrays,\nwhich downsampling would corrupt) — or `{\"available\": false, ...}` when the\nrun has no condition tree to evaluate (e.g. precomputed signals). Results\nexceeding the output cap are reduced further and explicitly marked\n`truncated_by_mcp` — never silently cut. Shaping only ever selects and thins\nwhat the engine returned; no value is computed or altered.\n\n## Error semantics\n\nDesigned for agents:\n\n- **Fixable by changing the request** → returned as a normal result: failed validations\n  arrive as `{\"valid\": false, \"errors\": [...]}` with machine codes and document\n  locations; engine rejections arrive as `{\"accepted\": false, \"error\": ...}` with a hint.\n- **Not fixable that way** → a tool error with explicit guidance: rate limits carry the\n  `Retry-After` value; engine-busy says retry with backoff; a compute timeout says\n  do **not** retry and reduce scope instead; permission problems name the missing\n  capability. Engine request ids are included for support.\n\n## Running the tests (self-host)\n\n```bash\npip install -e \".[dev]\"\npytest   # unit suite vs a mock engine — no network\n```\n\n## Questions / feedback\n\nQuestions or feedback? hello@backtest360.com — we read everything. backtest360-mcp is\nin active development, so help shape it.\n\nBug reports and feature requests: open an issue on GitHub.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 7739,
  "sha": "7dc0776baf3141420ba0d7e3c15898a880ceac47083089187fd52798e2396d2b",
  "repo_slug": "backtest360/backtest360-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_backtest360_backtest360_ecca39fd/readme"
}