bizonquant-mcp

BizonQuant 量化平台的 MCP server（客户端形态）：跑在你本机，把平台能力面开放给外部 agent（Claude Code / Cursor / Codex / 自写 agent），服务器零常驻进程、不开前端。

能力

当前源码提供 58 个工具：行情与因子、异步选股诊断、三类回测、批量试参、结果分档与对比、回测另存策略，以及交易面的盯盘复盘只读查询。组合/轮动可内联试参，子策略仍需本人已保存 ID。

先调 get_usage_guide_tool 读随包指南，或读取只读 resource bizonquant://guide；无需访问私仓。写配置前调 get_config_template_tool(section=...)，按需取 config、engine_config、rotation、portfolio、formula、caliber_changes（默认 all）。

账号与日历（3）

行情与个股（10）

因子与选股（7）

策略与模板（7）

回测提交与批量（5）

回测结果与对比（8）

组合与轮动（5）

盯盘与复盘（13）

交易面全部只读：下单/撤单/启停实盘/删方案/删策略/删回测不在能力面内，永远不会开放给 agent。

状态与边界

• 本地测试覆盖协议握手、工具调用和模板契约；测试结果以当前 CI/本次执行为准。本地通过不等于真实凭证与线上链路可用。
• 托管 Streamable HTTP、QuantBot/Python MCP 工具单源化、真实凭证 E2E、工具调用审计与更完整用户级限流仍需分别验证或建设。

三类回测共用每用户提交闸，排队+执行上限默认 3 个，与桌面端共享。提交429且提示并发上限时先等已有任务。degraded 是可取结果的终态，解读时保留质量标志。

日 K 仅查本地数据，不触发外部补数。研究池的特征写入链尚不完整，未接空壳工具。QuantBot 内置工具另有实现。

四条 MCP prompts 提供研究步骤：design_multifactor_strategy、diagnose_backtest、design_composite_strategy、review_trading_account；均引用现有工具，交易面只读。

批量回测与盯盘复盘

submit_backtest_batch_tool 以公共 config/preset_id/base_backtest_id 加1~30个带唯一 label 的补丁项试参；组合/轮动可用 kind+config 内联，子策略仍需已保存 ID。补丁对象深合并，null 删键、数组整体替换。默认 max_parallel=2，给桌面端留一个名额；账户总上限默认3，各宿主共享。单次提交遇429返回 submitted=false 与活跃任务；批次遇429退避后自动补位。

保存 batch_id，用 get_backtest_batch_tool 等待并取榜单；已有多个 ID 用 wait_backtests_tool。榜单不代表口径可比，先用 compare_backtests_tool 核对，再读五档结果与质量标记。满意后 save_strategy_from_backtest_tool 按当次配置另存，同名409不覆盖。cancel_backtest_batch_tool 默认仅停未提交队列，cancel_submitted=true 才取消已提交未终态回测。

批次仅在本地进程内存中。宿主重启会丢未提交项与批次状态；已提交任务仍在后端运行，按 list_backtests_tool 返回名称匹配 name_prefix 找回（需自行翻页匹配，无名称过滤参数）。

“今天调了吗／为何没调”从运行状态查托管任务与日志；“为什么卖了这只”查任务计划、信号 run、委托备注和实际成交；“分红到账了吗”查模拟盘现金账本。get_simulation_review_tool 还支持调仓计划、持仓变化、指定日回放和成交统计；各有历史窗口，空页不等于从未发生。批量快照可看自选/持仓新鲜度。部署、启动、停止托管必须由用户在桌面端操作。

安装与运行

# PyPI 安装，无需 clone；新增接口需要配套后端更新
uvx bizonquant-mcp@latest init     # 录入 key 并自检（写入 ~/.config/bizonquant-mcp/config.json，0600）
uvx bizonquant-mcp@latest doctor   # 探链路：health / token / whoami / 数据面

# 从源码运行
cd mcp-server && uv sync
uv run bizonquant-mcp doctor

接入 Claude Code（stdio）

// ~/.claude.json 的 mcpServers —— uvx 形态（推荐，无需本机有仓库）
"bizonquant": {
  "command": "uvx",
  "args": ["bizonquant-mcp@latest"],
  "env": {
    "BIZONQUANT_ACCESS_KEY": "bq_live_xxx",
    "BIZONQUANT_SECRET_KEY": "sk_yyy",
    "BIZONQUANT_BASE_URL": "https://bizon.naiyu.xyz:8443"
  }
}

// 仓库形态（开发调试用）
// "command": "uv", "args": ["--directory", "<仓库路径>/mcp-server", "run", "bizonquant-mcp"]

也支持单变量 BIZONQUANT_API_KEY=access_key.secret_key。

环境变量凭证缺失时，服务端会读取 init 写入的配置文件：默认 ~/.config/bizonquant-mcp/config.json，可用 BIZONQUANT_CONFIG 指定路径（空字符串仍用默认路径）。环境变量优先，缺项从配置文件补齐；base_url 也优先取环境变量，再取文件，最后取内置地址。不要把 secret 放进命令行或提交进仓库。

宿主超时与网络环境

宿主可能在工具返回前超时，MCP 的 HTTP 超时和宿主工具超时是两层限制。单条/多条等待默认总预算50秒，BIZONQUANT_WAIT_BUDGET_S 可调整默认值（最大600秒），显式 max_wait_s 优先；批次查询的 wait_s 默认50秒，实际取 wait_s、环境预算、600秒三者最小值，0为立即返回。放宽前也要调整宿主允许的工具时长，或保持短等待并续调。

选股提交后台任务，一次工具调用最多等待50秒；未完成返回 job_id，用 get_screen_job_tool 续查。同账号、同数据版本、相同请求会复用任务；终态最多保存15分钟：单账号超过16条记录或全局容量满时可能提前回收，engine重启也会丢失；返回404后原参数重新提交。旧同步 /screen 的55秒预算与 BIZONQUANT_SCREEN_TIMEOUT_S 仅供兼容路径使用。回测提交超时先按名称查历史，不能据超时断言未提交。指标预览 HTTP 超时120秒，宿主可能更早结束。

默认沿用系统代理环境；BIZONQUANT_TRUST_ENV=0 让 httpx 不读取环境代理等配置，适用于系统代理不可用或协议不支持的情况。它不改变网关地址、凭证权限或 HTTPS 校验要求。

拿凭证

1. 推荐：Agent 接入设置：设置 → 账号安全 →「Agent 接入 (MCP)」→ 生成新 Key；权限固定为 mcp.*，secret 一次性展示，可复制配置片段并管理已有 key。
2. 过渡 curl：登录（注意 device_type）→ POST /api/v1/api-keys（{"name":"mcp","permissions":["mcp.*"]}，secret 只显示一次）

当前网关按 scope=agent 统一限制操作，mcp.read / mcp.write 独立档位尚未实现，不能把标签当成独立只读权限保证。每个宿主/每台电脑各建一把 Key，同 Key 换发会互踢。

一个宿主一把 key：即使在同一台电脑，不同宿主进程也应分配独立 Key。

客户端纪律（内置，无需配置）

• 默认拒绝 http:// 明文网关（BIZONQUANT_ALLOW_INSECURE=1 可解锁内网场景）
• token 只走 Authorization 头；401 自动换发一次，仍 401 即停（key 撤销后不打风暴）
• UA 带 bizonquant-mcp/{version}，服务端可审计

安全模型

• 凭证是 API Key（access_key + secret），不是账号密码；Key 仍能读取用户的账户与交易记录，须妥善保管。
• 可读：行情、选股、回测、策略配置，以及账户、持仓、委托、成交、通知；业务归属鉴权仍生效。
• 不可读：LLM 配置与凭证、API Key 管理、后台管理。
• 不可做：任何交易与资金写（含下单、撤单、部署/启停托管）及删除。研究写操作仅限网关白名单，如保存多因子/组合/轮动策略、回测单次或批量提交与取消、完成回测另存策略。已部署策略（托管或实盘运行中、被 PTrade 订阅（含暂停中）、被已部署的组合引用）服务端拒绝 agent 覆盖（409），只能另存新名；覆盖其它同名策略前须征得用户明确同意。
• 删除 Key、停用或轮换 secret 可撤销对应访问；停止本机进程不等于服务端吊销凭证。
• revoke 命令 = 同 key 再换发一次（互踢规则下旧会话全灭）；永久吊销请在桌面端删 key

开发

uv run python -m pytest -q  # 全量测试（含网关 scope 与工具路径对拍、真实 stdio）
uv run bizonquant-mcp --version

对拍闸：tests/test_conformance.py 断言本包工具的 (method, path) ⊆ 网关 AGENT_WRITE_ALLOWLIST ∪ GET——网关收窄或工具新增写路径而网关未放行时，测试立即红。

tests/test_templates.py 以 AST 双向对拍后端字段与枚举，无需安装后端依赖；tests/test_guide.py 断言包内指南与仓库指南逐字节一致，并验证 resource/prompts。