Stock Tool MCP Server

English | 中文文档

一个强大且全面的模型上下文协议 (MCP) 服务器，专注于金融市场数据、技术分析和基本面研究。

🇨🇳 中文文档

📖 项目简介

本项目旨在为 AI Agent（如 Claude, Cursor, 通义千问等）赋予专业级的股市分析能力，打通大语言模型与实时金融数据之间的桥梁。

通过 MCP (Model Context Protocol) 协议，AI 可以直接调用本服务器提供的金融工具，实现：

• 📊 实时行情查询
• 📈 技术指标计算
• 💰 基本面分析
• 📰 新闻资讯获取
• 🔍 深度研究报告

🚀 核心功能

1. 多源市场数据融合

无需纠结使用哪个 API。本服务器内置智能 Adapter Manager（适配器管理器），可自动路由请求并在多个数据源之间进行故障转移：

• 美股: Yahoo Finance, Finnhub
• A股: Akshare, Tushare, Baostock
• 加密货币: CCXT (Binance, OKX 等)
• 外汇与指数: Yahoo Finance

2. 专业技术分析

内置量化分析引擎，提供的不仅仅是原始数字：

• 技术指标: SMA/EMA, RSI, MACD, 布林带 (Bollinger Bands), KDJ, ATR 等
• 形态识别: 自动检测 K 线形态（如十字星 Doji, 锤头线 Hammer, 吞没形态 Engulfing）
• 支撑与压力: 动态计算关键价格位
• 筹码分布 (Volume Profile): 分析成交量分布以识别价值区域

3. 深度基本面研究

自动化的金融分析师能力：

• 财务报表: 资产负债表、利润表、现金流量表
• 健康度打分: 基于盈利能力、偿债能力、成长性和估值的 0-100 分独家健康度评分
• 关键比率: PE, PB, ROE, ROA, 负债权益比等

4. 智能聚合工具

专为 LLM 上下文窗口优化：

• perform_deep_research: 一键获取指定标的的 价格 + 历史走势 + 基本面 + 近期新闻
• get_market_report: 获取当前市场状态的综合快照

🛠️ 安装指南

前置要求

• Python 3.10+
• Redis (可选，用于缓存)

安装步骤

1. 克隆仓库

   git clone https://github.com/yourusername/stock-tool-mcp.git
   cd stock-tool-mcp
   

2. 创建并激活 Conda 环境

   # 创建 Python 3.11.14 环境
   conda create -n stock-mcp python=3.11.14
   
   # 激活环境
   conda activate stock-mcp
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 配置环境变量

   复制示例环境变量文件:

   cp .env.example .env
   

   编辑 .env 添加你的 API 密钥（可选，但推荐以获得更高限额）:

   • TUSHARE_ENABLED - 是否启用 Tushare 数据源（默认 False）
   • TUSHARE_TOKEN - 用于 A 股数据（获取 Token）
   • TUSHARE_HTTP_URL - 可选，自定义 Tushare 接口地址（私有部署/镜像）
   • FINNHUB_ENABLED - 是否启用 Finnhub 数据源（默认 False）
   • FINNHUB_API_KEY - 用于美股机构数据（获取 API Key）
   • FRED_API_KEY - 用于美股宏观指标（GDP/CPI/失业率/利率，免费申请，获取 API Key）
   • DASHSCOPE_API_KEY - 用于阿里百炼 AI（可选，用于测试）

   💡 提示: 本项目采用可插拔设计。如果没有配置 API Key，系统会自动禁用相应的数据源，并使用免费的替代方案（如 Akshare, Baostock, Yahoo Finance）作为后备。

🏃‍♂️ 使用方法

方式一：作为 HTTP 服务器运行（推荐用于测试和开发）

使用 uvicorn 启动 MCP 服务器（Streamable HTTP 模式）：

# 设置环境变量指定传输方式为 streamable-http
export MCP_TRANSPORT=streamable-http

# 标准启动（监听 9898 端口）
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# 开发模式（支持热重载）
MCP_TRANSPORT=streamable-http python -m uvicorn src.server.app:app --reload --port 9898

启动成功后，你会看到：

✅ MCP server ready!

使用示例（Streamable HTTP）：

方式二：使用 stdio 模式（推荐用于 AI Agent 集成）

stdio 模式通过标准输入输出与 AI Agent 通信，适合 Claude Desktop、Cursor 等本地集成。

快速启动：

# 使用启动脚本（已配置好 conda 环境）
bash start_stock_mcp_stdio.sh

手动启动：

# 激活 conda 环境
conda activate stock-mcp

# 启动 stdio 模式（默认传输方式）
python -c "im...