TradingAgents MCP Server

将 TradingAgents 多智能体金融研究引擎，以标准 MCP 协议暴露给任意 LLM Host（Codex、Claude Desktop、Cursor 等）的薄适配层。

重要边界：本服务器只产出研究报告与非执行性决策。它不连接任何券商账户，不提交、修改或取消订单。研究结果仅供参考，不构成投资建议。

为什么需要它？

TradingAgents 本身是一个 Python 框架，需要通过编写代码或命令行方式驱动，LLM Host 无法直接调用它。TradingAgents MCP Server 解决了三个问题：

1. 零代码接入：LLM Host 通过 MCP 协议即可启动研究任务、查询进度、读取完整报告，无需理解 TradingAgents 内部结构。
2. 异步任务模型：完整金融研究耗时较长（数分钟到数十分钟），本服务器将每次分析建模为异步任务，不阻塞 MCP 调用。
3. 开箱即用的研究管线：内置任务队列、SQLite 持久化、幂等控制、取消与确认式删除，服务重启后任务状态不会丢失。

特性亮点

• 7 个 MCP 工具 + 1 个 MCP 资源：完整覆盖能力查询、任务启动、状态轮询、结果读取、任务列表、取消与删除。
• 异步任务状态机：queued → running → succeeded / failed / cancelled，支持长时间研究任务。
• 幂等创建：idempotency_key 保证同一分析请求重复提交只创建一次任务。
• 持久化存储：任务元数据存于 SQLite，报告与中间产物存于磁盘，服务重启后可恢复。
• 确认式删除：成果永不自动清理；删除必须传入完全匹配的 run_id 二次确认。
• 凭证隔离：LLM API Key 等敏感配置只存在于服务端环境变量中，MCP 协议层不接触凭证。

架构概览

flowchart LR
    A[LLM Host<br/>Codex / Claude Desktop] -->|MCP stdio| B[MCP Server<br/>tradingagents_mcp.server]
    B --> C[(SQLite<br/>tasks.db)]
    B --> D[TaskRuntime<br/>单 worker 串行队列]
    D -->|子进程隔离| E[worker.py]
    E --> F[TradingAgentsGraph<br/>propagate]
    F --> G[final_state.json<br/>complete_report.md]
    G --> B
    B -->|MCP Resource| A

• MCP Server：处理工具与资源请求，维护任务队列。
• SQLite：存储任务元数据与幂等映射，支持原子状态迁移。
• TaskRuntime：单 worker 串行执行任务，子进程隔离保证上游异常不影响服务器进程。
• worker.py：子进程内运行 TradingAgentsGraph.propagate()，产出 final_state.json 与 complete_report.md。

快速开始

前置要求

• Python 3.10+
• 已安装 TradingAgents：pip install tradingagents（或从源码安装）
• 已配置 LLM API Key（见下文「LLM 配置」）

安装

cd tradingagents-mcp
pip install -e .

启动

# 方式一：直接启动
python -m tradingagents_mcp.server

# 方式二：使用启动脚本（自动探测 TradingAgents 源码位置）
./start_server.sh

LLM 配置

LLM 提供商配置沿用 TradingAgents 自身的环境变量，由上游 TradingAgentsGraph 读取。MCP 适配器不接触这些凭证。

变量	说明	示例
TRADINGAGENTS_LLM_PROVIDER	LLM 提供商	openai、deepseek、custom_openai
TRADINGAGENTS_MODEL	深度思考模型名	deepseek-v4-flash
TRADINGAGENTS_QUICK_MODEL	快速思考模型名	deepseek-v4-flash
TRADINGAGENTS_BASE_URL	API 地址	https://api.example.com
TRADINGAGENTS_API_KEY	API Key（也可直接用 OPENAI_API_KEY、DEEPSEEK_API_KEY 等上游变量）	sk-...
TRADINGAGENTS_MAX_TOKENS	单次调用最大 token 数	4000
TRADINGAGENTS_TEMPERATURE	采样温度	0.7

服务端配置环境变量：

变量	说明	默认值
TRADINGAGENTS_MCP_DATA_DIR	数据目录（数据库、任务工作区）	~/.tradingagents-mcp
TRADINGAGENTS_MCP_MAX_QUEUED	最大排队任务数	20
TRADINGAGENTS_MCP_TASK_TIMEOUT	单任务超时（秒）	1800
TRADINGAGENTS_MCP_GRAPH_CLASS	上游图类导入路径（自定义安装布局时覆盖）	tradingagents.graph.trading_graph.TradingGraph

提示：所有凭证均以环境变量方式注入服务端进程，MCP 工具参数中永远不会出现 API Key。

配置到 MCP Host

Codex / Claude Desktop

{
  "mcpServers": {
    "tradingagents": {
      "command": "python",
      "args": ["-m", "tradingagents_mcp.server"]
    }
  }
}

工具与资源

工具	说明	只读	幂等
get_capabilities	查询服务器能力与配置（不含凭证）	✅	✅
start_analysis	启动分析任务	❌	✅（idempotency_key）
get_analysis_status	查询任务状态与时间戳	✅	✅
get_analysis_result	获取结果摘要（评级、置信度、报告 URI）	✅	✅
list_analyses	分页列出任务，支持状态过滤	✅	✅
cancel_analysis	取消 queued / running 任务	❌	✅
delete_analysis	永久删除任务（需 confirm_run_id 精确匹配）	❌	✅

MCP 资源：

• tradingagents://analyses/{run_id}/report — 完整的 Markdown 研究报告（仅 succeeded 任务可访问）

支持的资产与研究参数

参数	取值	说明
symbol	AAPL、600519.SH、BTC	股票代码或加密货币符号
asset_type	stock / crypto	默认 stock；stock 分析师为 market/social/news/fundamentals，crypto 为 market/social/news
analysis_date	YYYY-MM-DD	分析日期，不可为未来日期
depth	shallow / deep	默认 shallow（更快）；deep 更深入
language	English / 中文	默认 English
analysts	分析师类型列表	默认按 asset_type 决定
idempotency_key	可选字符串	相同参数 + 相同 key 返回已有任务

使用示例

1. 查询能力

调用 get_capabilities

返回支持的资产类型、研究深度、输出语言、队列限制等。

2. 启动分析

调用 start_analysis，参数：
- symbol: "AAPL"
- analysis_date: "2025-01-15"
- asset_type: "stock"
- depth: "shallow"
- language: "English"

返回 run_id，例如 run_a1b2c3d4e5f67890。

3. 轮询状态

调用 get_analysis_status，参数：
- run_id: "run_a1b2c3d4e5f67890"

任务状态流转：queued → running → succeeded / failed / cancelled。轮询直到终态。

4. 读取结果摘要

调用 get_analysis_result，参数：
- run_id: "run_a1b2c3d4e5f67890"

返回评级、置信度与报告资源 URI。

5. 阅读完整报告

通过 MCP 资源读取：

tradingagents://analyses/run_a1b2c3d4e5f67890/report

数据存储

所有数据存储在 TRADINGAGENTS_MCP_DATA_DIR（默认 ~/.tradingagents-mcp/）：

~/.tradingagents-mcp/
├── tasks.db            # SQLite 任务元数据数据库
└── runs/
    ├── run_abc123/     # 每个任务的独立工作区
    │   ├── request.json
    │   ├── final_state.json
    │   ├── complete_report.md
    │   ├── SUCCESS.json 或 error.json
    │   └── worker_stderr.log
    └── ...

• 任务成果永不自动清理，只有显式调用 delete_analysis 才会删除。
• 服务重启后，中断的 running 任务会自动重新入队。

安全与边界

• 不做交易：不连接券商，不提交、修改或取消任何订单。
• 凭证隔离：API Key 只存在于服务端环境变量，绝不通过 MCP 协议传输。
• 只读查询为主：除 start_analysis、cancel_analysis、delete_analysis 外，其余工具均为只读。
• 数据默认本地：报告与数据库存储在本地数据目录，不依赖外部 SaaS。

FAQ

Q：为什么不直接在 MCP Host 里调用 TradingAgents？ A：TradingAgents 是 Python 框架，LLM Host 无法原生执行任意 Python。MCP 适配器将研究能力封装为标准化工具，且提供队列、持久化、幂等、取消等工程能力。

Q：如何配置 API Key？ A：在启动 MCP 服务器的进程环境中设置 TRADINGAGENTS_API_KEY（或 OPENAI_API_KEY / DEEPSEEK_API_KEY）等变量。服务器不会通过 MCP 工具暴露或接收凭证。

Q：研究报告可以删除吗？ A：可以，但必须显式调用 delete_analysis 并传入完全匹配的 run_id。成果不会自动清理，避免误删。

Q：分析结果会过期或被覆盖吗？ A：不会。每个任务有独立工作区与持久化存储，幂等键保证同一请求只创建一次任务。

开发与测试

pip install pytest pytest-asyncio
pytest tests/

使用 MCP Inspector 交互式调试：

npx @modelcontextprotocol/inspector python -m tradingagents_mcp.server

许可证

MIT