How do I use BackTest_MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BackTest_MCP backtest a moving average crossover on AAPL from 2020-01-01 to 2023-12-31" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

BackTest_MCP

by Dor1Toes

Overview Schema Source Related Servers Discussions Admin

Python

Local

BackTest_MCP

股票回测引擎 MCP 服务器（QuantForge MCP）：面向 Cursor/Agent 的量化回测与数据服务。支持通过 MCP tools 执行“动态策略代码校验 → 拉取/缓存行情 → 子进程回测 → 产物/报告生成 → 结果查询”全流程。

主要技术栈：Python 3.10+、mcp（FastMCP，stdio/SSE）、SQLite（任务/行情/产物索引）、pandas/numpy（数据与指标计算）、akshare/yfinance（行情源，按 A 股/美股路由）、uvx/pyproject（可打包分发）、uvicorn（SSE 托管兼容）。

参考说明

本项目核心回测引擎代码参考自开源仓库 theNeuralHorizon/quantforge。在此基础上，结合 MCP 场景补充了工具化封装、服务层与运行流程。

Related MCP server: StocksMCP

功能概览

提供股票数据拉取/缓存能力（默认 auto 美股 + A股，yfinance 美股，akshare A股）。
提供动态策略代码校验与回测执行。
提供回测结果查询、工件下载、Markdown 报告生成。
提供策略信号扫描：读取已有 strategy/config，拉取最近行情，在最新 bar 检测信号并邮件通知。
暴露策略生成辅助目录（指标/统计/风控/组合函数与策略样例）。
支持多 Symbol（多标的）策略回测。
后续待开发：ML 能力完善与 Docker 化部署（如 worker/服务端容器化）。

文档

docs/quantforge_mcp.md：MCP 服务器层架构与模块说明
docs/quantforge_stock.md：回测/研究库架构与模块说明

目录结构

BackTest_MCP/
├─ pyproject.toml            # 打包配置（供 uvx 从 git 运行）
├─ requirements.txt          # Python 依赖（开发/兼容用）
├─ docs/                     # 架构与使用文档
├─ quantforge_mcp/           # MCP 服务包（server、tools、services、db、resources 等）
├─ quantforge_stock/         # 量化计算与策略库
└─ storage/
   ├─ db/                    # SQLite 数据库目录（包含 .db/.db-wal/.db-shm）
   └─ artifacts/             # 回测产物目录（按 job_id 划分）

> 注意：默认情况下，`storage/` 会**相对当前工作目录（cwd）**解析（例如你在 `C:\Users\username` 启动服务，则默认会落到 `C:\Users\username\storage\...`）。
> 如果在 `C:\Windows\System32` 等不可写目录启动，会自动回退到用户目录（如 `%LOCALAPPDATA%\\quantforge-mcp\\...`）。
> 如需固定位置，建议显式设置 `QUANTFORGE_DB_PATH` / `QUANTFORGE_ARTIFACTS_DIR` 为绝对路径。

环境要求

Python 3.10+

启动服务

方式 1：Cursor/Agent 通过 uvx 接入（推荐）

将以下配置加入 Cursor MCP 配置。@main 跟踪仓库最新代码；若需固定版本可改为 @v0.1.1 等 tag。

最简配置（env 可不填，回测与数据拉取照常可用）：

{
  "mcpServers": {
    "quantforge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Dor1Toes/BackTest_MCP.git@main",
        "quantforge-mcp"
      ]
    }
  }
}

可选 env（整块都可省略；按需取消注释并改成你的值）：

变量	是否必填	说明
`QUANTFORGE_DB_PATH` / `QUANTFORGE_ARTIFACTS_DIR`	否	不填时使用默认规则（cwd 下 `storage/`，不可写时自动落到用户目录，见 FAQ）
`QUANTFORGE_SMTP_` / `QUANTFORGE_NOTIFY_`	否	不填时 `scan_strategy_signals(..., notify=true)` 无法发邮件；扫描本身仍可用

固定数据目录示例（请替换 /path/to/quantforge-mcp 为本机绝对路径；Windows 也建议用正斜杠 /）：

{
  "mcpServers": {
    "quantforge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Dor1Toes/BackTest_MCP.git@main",
        "quantforge-mcp"
      ],
      "env": {
        "QUANTFORGE_DB_PATH": "/path/to/quantforge-mcp/db/quantforge.db",
        "QUANTFORGE_ARTIFACTS_DIR": "/path/to/quantforge-mcp/artifacts",
        "QUANTFORGE_SMTP_HOST": "smtp.example.com",
        "QUANTFORGE_SMTP_PORT": "465",
        "QUANTFORGE_SMTP_USER": "your@email.com",
        "QUANTFORGE_SMTP_PASSWORD": "your-app-password",
        "QUANTFORGE_NOTIFY_FROM": "quantforge@example.com",
        "QUANTFORGE_NOTIFY_TO": "you@example.com"
      }
    }
  }
}

（还未发布）如果未来发布到 PyPI，可使用以下形式（示例）：

{
  "mcpServers": {
    "quantforge": {
      "command": "uvx",
      "args": ["quantforge-mcp==0.1.0"],
      "env": { "QUANTFORGE_TRANSPORT": "stdio" }
    }
  }
}

方式 2：本地运行（开发/调试）

先安装依赖：

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

然后启动 stdio：

python -m quantforge_mcp

方式 3：SSE

set QUANTFORGE_TRANSPORT=sse   # Linux/macOS 用 export
set QUANTFORGE_SSE_PORT=8001
python -m quantforge_mcp

MCP 工具列表

Data

get_stock_data(symbols, start, end, interval, preview, preview_rows)：拉取/缓存 OHLCV；单票传 ["600519"]；preview=False 轻量返回，preview=True 附带 stats 与 head/tail 样例。
list_cached_symbols()：查看本地缓存股票代码。

Backtest

run_backtest_dynamic(code, config_json)：运行动态策略回测（策略代码与 config 在加载/执行前自动校验）。
list_backtest_jobs(limit, status)：列出 SQLite 中的历史回测 job。
get_backtest_result(job_id)：查询回测结果。
generate_backtest_report(job_id, title)：生成 Markdown 报告。
get_backtest_artifacts(job_id, kind)：获取回测工件。

Monitor

scan_strategy_signals(job_id, warmup_days_override, notify, notify_to)：读取回测 job 产物中的策略与配置，按 strategy.warmup() 拉取最近行情，在最新 bar 调用 on_bar；若有信号且 notify=true，通过 SMTP 发送邮件。

产物路径：自动定位 storage/artifacts/{job_id}/strategy.py 与 config.json（与 run_backtest_dynamic 产物一致）。

扫描节奏：读取 job 产物中的 config.json。rebalance=bar 时每次扫描最新 bar；rebalance=weekly|monthly 时默认仍扫描最新 bar，仅当配置了 last_rebalance_ts（YYYY-MM-DD）才按周/月 cadence 过滤是否调用 on_bar。

邮件环境变量（notify=true 时需要）：

QUANTFORGE_SMTP_HOST / QUANTFORGE_SMTP_PORT（默认 587）
QUANTFORGE_SMTP_USER / QUANTFORGE_SMTP_PASSWORD
QUANTFORGE_SMTP_USE_SSL（默认 false；端口 465 时自动启用 SSL 隐式加密）
QUANTFORGE_SMTP_USE_TLS（默认 true；非 SSL 模式下连接后启用 STARTTLS）
QUANTFORGE_NOTIFY_FROM / QUANTFORGE_NOTIFY_TO（收件人逗号分隔）

加密方式（二选一，按服务商选择）：

方式	典型端口	配置
SSL（隐式 TLS，`SMTP_SSL`）	465	设 `QUANTFORGE_SMTP_PORT=465` 即可；或任意端口 + `QUANTFORGE_SMTP_USE_SSL=true`
STARTTLS（先明文连再升级）	587	`QUANTFORGE_SMTP_PORT=587`，保持 `QUANTFORGE_SMTP_USE_TLS=true`（默认）

常见示例：

QQ / 163 邮箱：smtp.qq.com + 端口 465（自动走 SSL）
Gmail / Outlook：smtp.gmail.com / smtp.office365.com + 端口 587 + STARTTLS

也可在工具调用时通过 notify_to 单次覆盖收件人。

# 示例：扫描回测产物，不发邮件
scan_strategy_signals(job_id="36978bc8b0fb", notify=false)

策略示例

下面给出一个接入 MCP 后 Agent 应该生成的 “动量策略”示例策略代码与对应配置：

多标的说明：将 config_json.symbols 传入多个标的即可；引擎会在每个 bar 对每个 symbol 分别调用一次 on_bar(symbol, bar, history)（其中 history 为该 symbol 的单标的历史）。

示例策略代码（MomentumStrategy）

"""动量策略：60日收益率动量，正收益做多，负收益平仓。"""
from dataclasses import dataclass

import pandas as pd

from quantforge_stock.strategies.base import Strategy


@dataclass
class MomentumStrategy(Strategy):
    lookback: int = 60
    threshold: float = 0.0
    allow_short: bool = False
    name: str = "momentum"

    def warmup(self) -> int:
        return self.lookback + 1

    def on_bar(self, symbol: str, bar: pd.Series, history: pd.DataFrame) -> list:
        if len(history) < self.lookback + 1:
            return []
        past = history["close"].iloc[-(self.lookback + 1)]
        now = history["close"].iloc[-1]
        ret = now / past - 1.0
        direction = 0
        if ret > self.threshold:
            direction = 1
        elif ret < -self.threshold and self.allow_short:
            direction = -1
        strength = min(1.0, abs(ret) / max(self.threshold + 1e-6, 0.05))
        return [self._signal(bar.name, symbol, direction, strength, self.name)]

示例配置（config_json）

{
  "name": "ashare_momentum_real",
  "symbols": ["600519"],
  "start": "2025-07-23",
  "end": "2026-07-23",
  "initial_capital": 100000.0,
  "commission": 0.0003,
  "slippage": 0.001
}

MCP 资源列表

quantforge://codegen/spec：策略代码生成规范。
quantforge://data/symbol-guide：symbol 使用指南。
quantforge://examples/nvda_dynamic_config：动态回测配置示例。
quantforge://compute/modules：可用于策略生成的计算模块与函数目录。
quantforge://compute/{module}：查看单个计算模块详情（如 quantforge://compute/indicators）。
quantforge://strategies/index：内置策略示例索引。
quantforge://strategies/{name}：单个策略源码与说明（如 quantforge://strategies/ma_crossover）。

关键环境变量

所有配置项以 QUANTFORGE_ 为前缀：

QUANTFORGE_DB_PATH（默认 storage/db/quantforge.db，相对 cwd）
QUANTFORGE_ARTIFACTS_DIR（默认 storage/artifacts，相对 cwd）
QUANTFORGE_DATA_SOURCE（默认 auto）
QUANTFORGE_AKSHARE_ADJUST（默认 qfq）
QUANTFORGE_ALLOW_SYNTHETIC_FALLBACK（默认 true）
QUANTFORGE_SANDBOX_TIMEOUT_SEC（默认 120）
QUANTFORGE_TRANSPORT（stdio / sse，默认 stdio）
QUANTFORGE_SSE_PORT（默认 8001）
QUANTFORGE_SMTP_HOST / QUANTFORGE_SMTP_PORT / QUANTFORGE_SMTP_USER / QUANTFORGE_SMTP_PASSWORD（信号邮件通知）
QUANTFORGE_SMTP_USE_SSL（默认 false；端口 465 时自动 SSL）
QUANTFORGE_SMTP_USE_TLS（默认 true；非 SSL 时 STARTTLS）
QUANTFORGE_NOTIFY_FROM / QUANTFORGE_NOTIFY_TO（信号邮件发件人/收件人）

Windows 示例（将数据/产物固定到你的目录，路径请按本机修改）：

set QUANTFORGE_DB_PATH=D:/data/quantforge-mcp/db/quantforge.db
set QUANTFORGE_ARTIFACTS_DIR=D:/data/quantforge-mcp/artifacts

关于 `quantforge_stock/ml`

quantforge_stock/ml 目前处于开发中。

默认禁用；若你明确需要启用实验能力，请手动设置 QUANTFORGE_ENABLE_EXPERIMENTAL_ML=1。

set QUANTFORGE_ENABLE_EXPERIMENTAL_ML=1   # Linux/macOS 用 export

关于 sandbox 执行

动态回测通过 sandbox/worker/backtest_worker.py 以本地子进程方式运行（非 Docker）。超时由 QUANTFORGE_SANDBOX_TIMEOUT_SEC 控制；首次拉取行情/初始化数据库可能会稍慢。

常见问题

ModuleNotFoundError: quantforge_mcp
在仓库根目录执行 pip install -e . 后使用 python -m quantforge_mcp 或 quantforge-mcp；开发调试亦可用 pip install -r requirements.txt 再 python -m quantforge_mcp。
Cursor 日志提示：'uvx' 不是内部或外部命令
说明 Cursor 启动 MCP 的环境里找不到 uvx（PATH 未包含）。请将 mcpServers.quantforge.command 改成 uvx.exe 的绝对路径（例如 C:\\Users\\username\\.local\\bin\\uvx.exe），或确保 uvx 所在目录已加入系统 PATH。
uvx 从 C:\\Windows\\System32 等目录启动时报 ...\\storage\\db 创建失败
这是因为默认 storage/ 会相对当前工作目录（cwd）解析，导致尝试在系统目录下创建 storage/db。解决方式：
- 显式设置 QUANTFORGE_DB_PATH / QUANTFORGE_ARTIFACTS_DIR 为绝对路径
- 或设置 QUANTFORGE_STORAGE_ROOT 指向可写目录（将作为相对路径的基准）
更新版本后仍命中旧缓存
使用 uvx 时可在 args 最前追加 "--reinstall" 强制刷新缓存（例如 ["--reinstall", "--from", "git+...BackTest_MCP.git@main", "quantforge-mcp"]）。跟踪 @main 时建议在升级后 reinstall 一次。
首次回测较慢
首次拉取行情与初始化数据库会有冷启动开销，属于正常现象。

Available Tools

8 tools

generate_backtest_reportA

Build a Markdown tearsheet report from a completed backtest's equity curve.

Args: job_id: Completed backtest job (must have an equity_curve artifact). title: Optional report heading; defaults to "Backtest {job_id}".

Returns: On success: {"ok": true, "job_id": str, "title": str, "format": "markdown", "path": str, "content": str}. Also registers a report_markdown artifact. On missing equity curve: {"ok": false, "error": str}.

ParametersJSON Schema

Name	Required	Description	Default
`title`	No
`job_id`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses success/failure return shapes, the side effect of registering a report_markdown artifact, and the default title behavior, which is beyond minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a leading purpose sentence followed by clearly labeled Args and Returns sections. No redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers prerequisites, parameters, return types, error cases, and side effects. For a simple report generator with no annotations or output schema, it is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description fully describes both parameters: job_id's requirement for an equity_curve artifact and title's optionality with a computed default, adding critical meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Build a Markdown tearsheet report from a completed backtest's equity curve.' This clearly distinguishes it from siblings like get_backtest_result or run_backtest_dynamic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the prerequisite that the job_id must refer to a completed backtest with an equity_curve artifact, implying when to use it. However, it does not explicitly name alternative tools or provide when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_backtest_artifactsA

List on-disk artifact paths for a backtest job.

Args: job_id: Backtest job identifier. kind: Optional filter: equity_curve, trades, stdout, stderr, strategy_code, or report_markdown; empty returns all kinds.

Returns: {"ok": true, "job_id": str, "artifacts": [{"kind": str, "path": str, ...}]}.

ParametersJSON Schema

Name	Required	Description	Default
`kind`	No
`job_id`	Yes

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the return structure (JSON with ok, job_id, artifacts) and artifact entry fields, which is helpful. However, it does not mention error behavior (missing job_id), path details, or permissions, leaving some behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a clear summary line followed by Args and Returns sections. Every sentence adds value, and the format is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter listing tool with no output schema or annotations, the description provides the essential purpose, parameters, and return format. It lacks edge-case behavior (e.g., invalid job_id) but is otherwise sufficient for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The Args section documents both parameters: job_id as 'Backtest job identifier' and kind with an explicit list of valid filters plus the empty-all behavior. This fully compensates for the 0% schema description coverage, adding meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opener 'List on-disk artifact paths for a backtest job' uses a specific verb (List) and resource (artifact paths), clearly distinguishing it from sibling tools like get_backtest_result (result data) and list_backtest_jobs (job listing). The filter kinds are enumerated, reinforcing scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies that kind is an optional filter and that empty returns all kinds, giving clear context for when to use this tool with filtering. However, it does not explicitly contrast with siblings or state when not to use it, so it stops short of full usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_backtest_resultA

Fetch status and summary for a backtest job stored in SQLite.

Args: job_id: Job identifier returned by run_backtest_dynamic.

Returns: {"ok": true, "job_id": str, "status": str, "job_type": str, "error_message": str|null, "result": dict|null} where result holds metrics and metadata when status is "done". On unknown job: {"ok": false, "error": str}.

ParametersJSON Schema

Name	Required	Description	Default
`job_id`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of explaining behavior. It fully documents the return schema, including the `ok` flag, status, error handling, and the `result` field conditionally populated when status is `'done'`. It also covers the unknown job case. It doesn't mention replication or side effects, but for a fetcher that's a reasonable trade-off.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with an Args section and a Returns section, both concise and free of fluff. Every sentence adds value, and the return format is presented in a compact but complete manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter fetch operation, the description is fully sufficient. It specifies input provenance, success and error return shapes, and conditional behavior of the `result` field. No output schema exists, but the description provides one inline, ensuring the agent understands what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema provides only the name and type of `job_id`, the description explains it is a 'Job identifier returned by `run_backtest_dynamic`'. This provenance clue adds essential meaning beyond the schema, fully compensating for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch status and summary') and the resource ('a backtest job stored in SQLite'). It distinguishes itself from sibling tools like get_backtest_artifacts and list_backtest_jobs by focusing on job results rather than artifacts or a list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by referencing `run_backtest_dynamic` as the source of `job_id`, implying this tool is used after starting a backtest. However, it doesn't explicitly mention when not to use it or suggest alternative tools for other needs (e.g., get_backtest_artifacts for file outputs).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_stock_dataA

Fetch and cache OHLCV bars for one or more symbols from local DB or remote source.

Args: symbols: Non-empty list of ticker codes; pass a single symbol as ["600519"]. Symbol formats: quantforge://data/symbol-guide. start: Start date YYYY-MM-DD; empty uses a default lookback window. end: End date YYYY-MM-DD; empty defaults to today. interval: Bar interval (default "1d"). preview: When false, returns row counts only; when true, adds stats and head/tail samples. preview_rows: Number of head/tail rows per symbol when preview=True (default 3).

Returns: {"ok": true, "start": str, "end": str, "interval": str, "items": [...]} where each item has symbol, rows, source, and optional preview fields. On empty symbols: {"ok": false, "error": str}.

ParametersJSON Schema

Name	Required	Default
`end`	No
`start`	No
`preview`	No
`symbols`	Yes
`interval`	No	1d
`preview_rows`	No

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses caching behavior, preview modes, return structure, and an error case for empty symbols. It also provides default values and source selection. Missing details like network access or permission requirements, but the coverage is strong for a data-fetching tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args and Returns sections, front-loads the purpose, and every sentence adds value. It is detailed yet concise, with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with no output schema and no annotations, the description provides a complete picture: purpose, all parameter semantics, return structure, and an error condition. It does not cover edge cases like invalid symbol format or start > end, but the core usage is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are 0%, so the description fully carries parameter meaning. It explains every parameter: symbols format with an example, date formats and defaults, interval default, preview behavior, and preview_rows default. This is far beyond the basic schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific action ('Fetch and cache OHLCV bars') on a specific resource ('one or more symbols') with source context ('local DB or remote source'). This clearly distinguishes it from backtest-related sibling tools, though it slightly overlaps with list_cached_symbols.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. While it explains parameter usage and defaults, it does not mention any exclusions or alternative tools, leaving the selection decision ambiguous given siblings like list_cached_symbols.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_backtest_jobsA

List recent backtest jobs from SQLite, newest first.

Args: limit: Maximum number of jobs to return (default 50). status: Optional filter, e.g. "done" or "failed"; empty string returns all.

Returns: {"ok": true, "count": int, "jobs": [...]} where each job includes job_id, status, strategy_name, symbols, start, end, total_return, max_drawdown, n_trades, timestamps, and error_message.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`status`	No

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It does disclose data source (SQLite), ordering (newest first), and the full return structure, which is helpful. However, it does not explicitly state that this is a read-only operation or note any side effects or limitations beyond the basic list behavior. The verb 'list' implies non-mutation, but explicit disclosure would be stronger.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args and Returns sections. Each sentence contributes value: the one-line summary gives the core purpose, the Args section explains both parameters, and the Returns section defines the output shape. No redundant or filler content exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (two optional parameters) and has no output schema, so the detailed Returns section is valuable and makes the description reasonably complete. It covers payload structure and field lists. A minor gap is that it doesn't define any maximum or bounds on the limit parameter, but this is not critical for a listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only names, types, and defaults (0% schema description coverage). The description compensates fully: it explains the limit parameter with a default and meaning, and the status parameter with example values ('done', 'failed') and behavior for empty string. This adds substantial semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List recent backtest jobs from SQLite, newest first.' It uses a specific verb ('list'), a specific resource ('backtest jobs'), and a scope ('recent', 'newest first'). This differentiates it from sibling tools like get_backtest_result, which likely retrieves a single job, and run_backtest_dynamic, which runs new jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context (listing recent jobs from SQLite) but does not explicitly explain when to use this tool versus alternatives like get_backtest_result or run_backtest_dynamic. There is no mention of exclusions or alternative tools, so the guidance is only implied by the action verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_cached_symbolsA

List stock symbols that already have OHLCV data in the local SQLite cache.

Returns: {"ok": true, "symbols": [str, ...]}.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the local SQLite cache as the data source and explicitly provides the return JSON format, which is beyond what the empty input schema offers. Although it does not explicitly state that the operation is read-only, 'List' and 'cache' imply non-destructive behavior. This is sufficient for a simple listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states purpose, the second gives the return type. Every word adds value and it is front-loaded. No extraneous information or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple: no parameters, no output schema, and the description covers both what it does and the exact return structure. The mention of 'local SQLite cache' and the return format fully equips an agent to invoke and interpret the result. There is no missing critical context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema is trivially 100% covered. According to the rubric, 0 parameters yields a baseline of 4. The description adds no parameter details (there are none), so no additional credit or penalty is applied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List stock symbols that already have OHLCV data in the local SQLite cache.' It uses a specific verb ('List'), identifies the resource ('stock symbols'), and includes a distinguishing qualifier ('already have OHLCV data in the local SQLite cache') that separates it from sibling tools like get_stock_data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys when to use the tool: to check which symbols already have cached OHLCV data. However, it does not explicitly mention alternatives or when not to use it, so it lacks the explicit exclusion/alternative guidance required for a 5. The context is clear, earning a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_backtest_dynamicA

Run a dynamic Strategy backtest in an isolated sandbox and persist artifacts.

Args: code: Python source with exactly one Strategy subclass. Strategy rules and allowed imports are enforced before execution; see quantforge://codegen/spec. config_json: JSON string for backtest settings (required: symbols; optional: name, start, end, initial_capital, commission, slippage, target_weights, sizing_fraction, rebalance, last_rebalance_ts, history_tail). Dates must be YYYY-MM-DD. Full schema and examples: quantforge://codegen/spec.

Returns: On success: {"ok": true, "job_id": str, "status": "done", "result": {...}} where result includes metrics (total_return, max_drawdown, n_trades, ...). On validation failure: {"ok": false, "validation": {...}} (no job created). On runtime failure: {"ok": false, "job_id": str, "status": "failed", "error": str}.

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes
`config_json`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so excellently. It discloses sandbox isolation, pre-execution validation, validation failure (no job created), runtime failure (job_id plus error), and success result with metrics. It also hints at artifact persistence, giving the agent a clear behavioral model.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is logically structured with a summary, Args, and Returns sections. It is moderately long but every part serves a purpose. The spec URI is repeated twice, which is slightly redundant, but the overall organization keeps it readable and efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two complex string parameters and no output schema, the description fully covers the important aspects: success, validation failure, and runtime failure responses, plus a preview of the metrics returned. It also references a spec for deeper details, making it self-contained enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are absent (0% coverage), so the description fully compensates. It explains `code` as Python source with exactly one Strategy subclass and enforced imports, and `config_json` as a JSON string with required/optional settings, date format, and pointer to full schema. This adds substantial meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific verb and resource: 'Run a dynamic Strategy backtest in an isolated sandbox and persist artifacts.' This clearly states what the tool does and distinguishes it from siblings like get_backtest_result or scan_strategy_signals. The 'dynamic' and 'persist artifacts' add specificity beyond the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: it runs backtests, enforces strategy rules, and returns a job_id for later retrieval. It does not explicitly name alternative tools or state when not to use it, but the context makes the primary use case obvious. This aligns with 'clear context, no exclusions'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_strategy_signalsA

Scan the latest bar for live strategy signals from a saved backtest job.

Loads strategy.py and config.json from storage/artifacts/{job_id}/. Fetches recent OHLCV through today; the calendar-day window is derived from strategy.warmup() unless overridden.

Args: job_id: Backtest job whose artifacts contain the strategy and config. warmup_days_override: Optional calendar days of history to fetch; overrides the default warmup-based window when set. notify: When true and signals exist, send email via configured SMTP (QUANTFORGE_SMTP_* / QUANTFORGE_NOTIFY_* env vars). notify_to: Optional recipient override; defaults to QUANTFORGE_NOTIFY_TO.

Returns: {"ok": bool, "strategy_name": str, "symbols": [...], "data_range": {...}, "signals": [{symbol, direction, strength, strategy_id, bar_date, close}], "warnings": [...], "notified": bool, "notify_error": str|null}. On missing files or invalid config: {"ok": false, "error": str} or {"ok": false, "validation": {...}}. Config fields (rebalance, last_rebalance_ts, history_tail) follow quantforge://codegen/spec.

ParametersJSON Schema

Name	Required	Description	Default
`job_id`	Yes
`notify`	No
`notify_to`	No
`warmup_days_override`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does excellently. It discloses internal mechanics (loads strategy.py and config.json from storage/artifacts/{job_id}/), data fetching behavior, the warmup-based window, email side effects when notify is true, and detailed error/return behavior for missing files or invalid config.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening sentence, followed by an overview paragraph and organized Args/Returns sections. It is longer than strictly necessary but every section adds valuable context. It earns a 4, not a 5, because the level of detail (especially the full return shape) could be slightly trimmed without losing core meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a tool with no output schema and no annotations. It covers the purpose, all parameters, the exact return shape under success and failure, side effects (notification), and even references the config spec. There are no significant gaps that would leave an agent uncertain about invocation or interpretation of results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates fully by explaining every parameter in the Args section: job_id, warmup_days_override, notify, and notify_to. It adds meaning beyond the bare schema types and defaults, including the purpose of each argument and how overrides work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb and resource: 'Scan the latest bar for live strategy signals from a saved backtest job.' This immediately distinguishes it from sibling tools like get_backtest_result or run_backtest_dynamic, which focus on historical results or running backtests, not live signal scanning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys when to use the tool (for live signals derived from a saved backtest) and explains the process (loads artifacts, fetches OHLCV, optional notify). However, it does not explicitly name alternatives or state when NOT to use it, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

8 tool updatesv0.1.0Aug 12, 2026
- First observedgenerate_backtest_report
- First observedget_backtest_artifacts
- First observedget_backtest_result
- First observedget_stock_data
- First observedlist_backtest_jobs
- First observedlist_cached_symbols
- First observedrun_backtest_dynamic
- First observedscan_strategy_signals

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-08-12 07:15 across 8 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: data fetching, cache listing, running backtests, retrieving results, listing jobs, generating reports, accessing artifacts, and scanning live signals. No two tools overlap in function, even though several relate to backtests but target different aspects (results vs artifacts vs jobs).

Naming Consistency4/5

The naming follows a verb_noun pattern with prefixes like get_, list_, run_, generate_, and scan_. The mix of get_backtest_result and get_backtest_artifacts vs list_backtest_jobs and list_cached_symbols is syntactically consistent, though get vs list could be unified. Overall it is predictable and readable.

Tool Count5/5

Eight tools is ideal for a backtesting MCP server. The scope is tightly focused on data retrieval, backtest execution, result inspection, artifact access, reporting, and live signal generation—each tool addresses a distinct step in the workflow with no redundancy or bloat.

Completeness5/5

The tool surface covers the full lifecycle: fetching market data, running dynamic backtests, retrieving results and artifacts, listing historical jobs, generating reports, and scanning live signals. There are no obvious missing operations for the domain; the set is comprehensive and self-contained.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
dMoERA Creator B
io.github.CacheCarti
Build, backtest, and deploy crypto trading strategies via MCP with 7-stage validation.
Cryptocurrency Finance
4419
quant-brain-mcp C
io.github.paarths-collab
Stock analysis MCP: 38 indicators, 7 optimizers, 8 backtests, US + India sectors.
Finance AI & Machine Learning
2524
MCP Server for Zerodha Kite Connect APIOAuth
io.github.Sundeepg98
Open-source MCP server for Zerodha Kite Connect. Portfolio, market data, backtesting, alerts.
Finance Search Monitoring
2

Related MCP Servers

AI-Kline MCP Server
Finance AI & Machine Learning Data Visualization
QuantMLResearch
F
license
Not graded
quality
D
maintenance
MCP server for A-share stock technical analysis and AI prediction, enabling LLM-based interaction to analyze stocks.
Updated a year ago (2025-08-06 02:37 UTC)
342
-
StocksMCP
Finance Data Visualization
pawanthanay
F
license
Not graded
quality
D
maintenance
AI-powered stock research MCP server with real-time data, CRUD operations, and interactive dashboard for fundamental analysis and comparisons.
Updated 3 months ago (2026-06-08 18:52 UTC)
-
backtest360-mcpofficial
Finance Research & Data
Backtest360
A
license
A
quality
D
maintenance
MCP server that exposes the Backtest360 backtesting engine API as tools, enabling AI agents to conversationally discover indicators, build and validate strategies, run backtests, and read results.
Updated 2 months ago (2026-07-29 22:15 UTC)
14
60 PyPI
MIT
Litmus
Finance Research & Data
Spectrexf
A
license
Not graded
quality
C
maintenance
An MCP server that lets an AI agent backtest, risk-check, and audit trading strategies, determining if a strategy is overfit or actually works.
Updated 3 months ago (2026-06-27 22:20 UTC)
MIT

BackTest_MCP

参考说明

功能概览

文档

目录结构

环境要求

启动服务

方式 1：Cursor/Agent 通过 uvx 接入（推荐）

方式 2：本地运行（开发/调试）

方式 3：SSE

MCP 工具列表

Data

Backtest

Monitor

策略示例

示例策略代码（MomentumStrategy）

示例配置（config_json）

MCP 资源列表

关键环境变量

关于 quantforge_stock/ml

关于 sandbox 执行

常见问题

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

backtest360-mcpofficial

关于 `quantforge_stock/ml`