✨ 为什么选择 Stock MCP？

• 🌐 全球市场覆盖 - 一键接入 A股、港股、美股数据
• 🤖 AI 智能分析 - 新闻情绪分析、深度研究报告、智能搜索
• 🚀 开箱即用 - Docker 一键部署，5分钟启动服务
• 📊 多数据源融合 - AKShare、Tushare、yFinance、Finnhub 智能聚合
• 🏛️ 宏观经济数据 - GDP、CPI、PMI、货币供应量等全面覆盖
• 🧪 快速测试工具 - 内置接口测试页面，可视化API调试
• 💾 高性能缓存 - Redis 加速 + 自动降级，稳定可靠

🚀 快速开始

# 1. 克隆项目
git clone [email protected]:huweihua123/stock-mcp.git && cd stock-mcp

# 2. 配置环境变量（必需：TUSHARE_TOKEN）
cp .env.example .env && vim .env

# 3. 一键启动
docker-compose up -d

# 4. 访问服务
open http://localhost:9998/docs

# 5. 快速测试页面（可视化API调试）
open http://localhost:9998/

💡 查看样例报告: 想了解 AI 分析能力?查看 样例报告 了解完整的技术分析和基本面报告格式

🎯 5分钟体验核心功能：

# 查询茅台历史价格及AI分析
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# 获取苹果实时行情
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# 查询股票基本面数据
curl "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01"

# 批量查询多只股票
curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

# 查询宏观经济数据
curl "http://localhost:9998/api/macro/gdp?start_date=2020-01-01&end_date=2024-12-31"

🎨 可视化测试: 访问 http://localhost:9998/ 使用内置的接口测试工具，无需命令行即可快速测试所有API

🎯 核心功能

📋 API 接口概览

💡 提示: 所有接口支持 A股、港股、美股三大市场
📚 详细文档: 启动后访问 http://localhost:9998/docs
🧪 快速测试: 访问 http://localhost:9998/ 使用可视化测试工具

⚙️ 配置说明

核心配置（.env 文件）

# 【必填】A股数据访问（申请地址：https://tushare.pro/）
TUSHARE_TOKEN=your_token_here

# 【可选】代理配置（访问美股数据时推荐）
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890

# 【可选】增强功能
TAVILY_API_KEY=your_key     # AI 搜索和研究
FINNHUB_API_KEY=your_key    # 增强新闻数据
NEWS_API_KEY=your_key       # 新闻聚合

🧪 接口测试工具

🎯 快速开始测试

无需安装任何工具，直接在浏览器中测试所有API接口：

1. 启动服务: docker-compose up -d
2. 打开测试页面: http://localhost:9998/
3. 选择接口: 从左侧面板选择要测试的API
4. 填写参数: 自动填充常用参数，支持自定义修改
5. 发送请求: 一键测试，实时查看响应结果

✨ 功能特性

• 🎨 可视化界面 - 直观的API分类和参数表单
• 🔄 实时测试 - 即时发送请求并显示响应
• 🎯 参数预填 - 智能填充常用股票代码和日期
• 📝 结果高亮 - JSON响应自动格式化和语法高亮
• 📊 多接口支持 - 覆盖股票、宏观经济、交易日历所有接口
• 🌐 响应式设计 - 支持桌面和移动设备

📱 界面截图

🚀 常用测试场景

🔹 股票数据测试
   • 查询贵州茅台(600519)历史价格和技术分析
   • 获取苹果(AAPL)实时行情快照
   • 批量查询多只热门股票

🔹 宏观经济数据测试
   • 查询最近5年GDP增长趋势
   • 获取CPI、PPI通胀数据对比
   • 分析货币供应量变化

🔹 交易日历测试
   • 检查节假日是否为交易日
   • 获取指定时间段的所有交易日
   • 查询不同交易所的交易时间

📡 API 接口文档

🎨 交互式文档

启动服务后访问以下地址查看完整的 Swagger UI 文档：

• Swagger UI: http://localhost:9998/docs - 完整的OpenAPI文档
• ReDoc: http://localhost:9998/redoc - 另一种文档风格
• 🧪 API 测试工具: http://localhost:9998/ - 可视化接口测试页面

💡 推荐使用: API测试工具提供了友好的界面，支持股票、宏观经济、交易日历等所有接口的快速测试，支持参数自动填充和响应结果高亮显示。

📋 样例报告

查看完整的 AI 分析报告样例：

• 📊 技术分析报告
  • 贵州茅台 (600519) - A股白酒龙头技术分析
  • 腾讯控股 (0700) - 港股科技股技术分析
  • 苹果 (AAPL) - 美股科技巨头技术分析
• 💼 基本面分析报告
  • 贵州茅台基本面 (600519) - 财务指标深度分析
  • 腾讯控股基本面 (0700) - 港股财务数据分析
• 📁 原始数据样例
  • 贵州茅台财务数据 (JSON) - 完整财务数据结构

📊 股票数据接口

{
  "status": "success",
  "message": "成功获取股票价格数据和分析报告",
  "data": "# AAPL 股票分析报告\n\n## 📊 基本信息\n- **股票名称**: 苹果公司\n- **股票代码**: AAPL\n- **分析期间**: 2025-07-12 至 2025-08-12\n\n## 💰 价格表现\n- **当前价格**: $227.18\n- **期间涨跌**: $+18.80 (+9.02%)\n- **期间最高**: $230.74\n- **期间最低**: $201.27\n- **平均成交量**: 60,489,490\n\n## 📈 技术指标\n- **5日均线**: $218.35\n- **20日均线**: $212.25\n- **近期趋势**: 上升"
}

curl -X GET "http://localhost:9998/stock/price?symbol=AAPL&start_date=2024-07-13&end_date=2025-07-13"

curl -X GET "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01" 

{
  "status": "success",
  "message": "成功获取 AAPL 的实时行情",
  "data": {
    "ticker": "AAPL",
    "currentPrice": "256.48",
    "dailyChangePercent": "-0.0818107444777616",
    "peRatio": "38.919575",
    "marketCap": "3806263246848",
    "source": "yfinance"
  }
}

curl -X GET "http://localhost:9998/api/stock/news?symbol=AAPL" 

curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

📰 新闻数据接口

curl -X GET "http://localhost:9998/api/stock/news?symbol=000001"

curl -X GET "http://localhost:9998/api/stock/news/date?symbol=000001&target_date=2025-09-10&days_before=7"

📅 交易日历接口

curl -X GET "http://localhost:9998/api/calendar/trading-days?symbol=000001&start_date=2025-01-01&end_date=2025-09-01" \

curl -X GET "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=2025-09-30" \

curl -X GET "http://localhost:9998/api/calendar/trading-hours?symbol=000001&check_date=2025-09-30" \

{
  "status": "success",
  "message": "成功获取支持的交易所列表",
  "data": {
    "total_count": 200,
    "regions": {
      "美国": ["NYSE", "NASDAQ"],
      "中国": ["XSHG", "XSHE"],
      "欧洲": ["XPAR", "XLON"],
      "亚太": ["NSE", "TSE"],
      "加拿大": ["TSX"]
    },
    "all_exchanges": ["NYSE", "NASDAQ", "XSHG", "XSHE", "..."]
  }
}

curl -X GET "http://localhost:9998/api/calendar/supported-exchanges" \

🏛️ 宏观经济数据接口

{
  "status": "success",
  "message": "成功获取GDP数据",
  "data": [
    {
      "季度": "2024年第3季度",
      "国内生产总值_当季值": "306480.0",
      "国内生产总值_累计值": "913027.0",
      "国内生产总值_同比增长": "4.6",
      "国内生产总值_累计同比增长": "4.8"
    }
  ]
}

curl -X GET "http://localhost:9998/api/macro/gdp?start_date=2020-01-01&end_date=2024-12-31" \

{
  "status": "success",
  "message": "成功获取CPI数据",
  "data": [
    {
      "月份": "2024年09月",
      "全国_当月": "100.4",
      "全国_累计": "100.3",
      "城市_当月": "100.4",
      "城市_累计": "100.4",
      "农村_当月": "100.5",
      "农村_累计": "100.1"
    }
  ]
}

curl -X GET "http://localhost:9998/api/macro/cpi?start_date=2020-01-01&end_date=2024-12-31" \

curl -X GET "http://localhost:9998/api/macro/pmi?start_date=2020-01-01&end_date=2024-12-31" \

curl -X GET "http://localhost:9998/api/macro/ppi?start_date=2020-01-01&end_date=2024-12-31" \

curl -X GET "http://localhost:9998/api/macro/money-supply?start_date=2020-01-01&end_date=2024-12-31" \

curl -X GET "http://localhost:9998/api/macro/lpr?start_date=2020-01-01&end_date=2024-12-31" \

curl -X GET "http://localhost:9998/api/macro/social-financing?start_date=2020-01-01&end_date=2024-12-31" \

🔐 认证说明

所有API接口均支持可选的 Authorization Header 进行身份验证：

-H "Authorization: your-api-token-here"

获取Token: 请联系管理员或在配置文件中设置自定义Token。

📊 快速测试

使用以下命令快速测试主要接口：

# 查询茅台股价
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# 获取苹果实时行情
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# 检查今天是否为交易日
curl "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=$(date +%Y-%m-%d)"

# 获取所有支持的交易所
curl "http://localhost:9998/api/calendar/supported-exchanges"

# 查询GDP数据
curl "http://localhost:9998/api/macro/gdp?start_date=2020-01-01&end_date=2024-12-31"

# 查询CPI数据
curl "http://localhost:9998/api/macro/cpi?start_date=2023-01-01&end_date=2024-12-31"

🎨 可视化测试: 访问 http://localhost:9998/ 可以直接在浏览器中测试所有接口，无需命令行操作

📖 API 设计规范

本项目API遵循以下设计原则：

✅ RESTful风格 - 使用标准HTTP方法(GET/POST)
✅ 统一响应格式 - 所有接口返回统一的JSON结构
✅ 详细错误信息 - 错误响应包含明确的错误码和描述
✅ OpenAPI 3.0 - 完整的API规范文档(查看)
✅ 自动文档生成 - Swagger UI + ReDoc双文档支持

📊 数据源说明

股票数据

• A股数据: Tushare Pro - 专业金融数据接口
• 港股美股: yFinance - Yahoo Finance API
• 补充数据: AKShare - 开源金融数据库

宏观经济数据

• GDP数据: 国家统计局官方发布的季度GDP数据
• CPI/PPI: 国家统计局月度消费者/生产者价格指数
• PMI数据: 中国物流与采购联合会发布的采购经理指数
• 货币供应量: 中国人民银行发布的M0、M1、M2数据
• LPR利率: 贷款市场报价利率，央行每月发布
• 社会融资规模: 央行统计的社会融资规模存量和增量数据

新闻资讯

• AI增强搜索: Tavily API - 智能搜索和摘要
• 多源聚合: Finnhub + NewsAPI

数据更新频率

• 实时行情: 市场开盘期间实时更新
• 基本面数据: 财报发布后及时更新
• 宏观数据: 官方发布后1-2个工作日内更新
• 新闻数据: 实时抓取，每小时刷新

🐳 Docker 部署

服务架构

常用命令

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f stock-mcp

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 重新构建
docker-compose up -d --build

🛠️ 故障排查

# 检查配置
cat .env | grep REDIS_HOST
# 确保 Docker 环境使用: REDIS_HOST=redis

# 检查 Redis 状态
docker-compose ps redis

# 检查代理配置
cat .env | grep PROXY
# Docker 环境应使用: HTTP_PROXY=http://host.docker.internal:7890

grep TUSHARE_TOKEN .env

更多问题：完整故障排查指南

📚 文档

• 📡 完整 API 文档 - 所有接口详细说明、参数、示例
• 💡 API 使用示例 - 实际场景的代码示例
• 📖 使用指南 - 配置、部署、最佳实践
• 🔧 开发文档 - 架构设计、二次开发
• 🌐 OpenAPI 规范 - 标准API规范文件
• 💻 Swagger UI - 交互式API测试(服务启动后访问)

🆕 更新日志

v2.1.0 (2025-10-13)

• ✨ 新增宏观经济数据接口 - 支持GDP、CPI、PMI、PPI、货币供应量、LPR、社会融资规模
• 🧪 内置API测试工具 - 可视化接口测试页面，支持所有API的快速测试
• 📊 数据监控面板 - 实时展示数据获取状态和性能指标
• 🚀 性能优化 - 改进缓存策略，提升数据查询速度
• 📚 文档完善 - 新增宏观数据说明和测试工具使用指南

v2.0.0 (2025-09-15)

• 🔄 架构重构 - 基于MCP协议的全新架构
• 🌐 多市场支持 - 完整的A股/港股/美股数据覆盖
• 🤖 AI分析增强 - 集成GPT的智能分析报告
• 🐳 容器化部署 - Docker一键部署方案

🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

# 1. Fork 项目
# 2. 创建特性分支
git checkout -b feature/amazing-feature

# 3. 提交代码
git commit -m "Add: amazing feature"

# 4. 推送并创建 PR
git push origin feature/amazing-feature

📄 开源协议

MIT License - 详见 LICENSE