基于 Model Context Protocol 的智能股票数据服务
一站式获取 A股/港股/美股实时数据 + AI 驱动的深度分析
- 🌐 全球市场覆盖 - 一键接入 A股、港股、美股数据
- 🤖 AI 智能分析 - 新闻情绪分析、深度研究报告、智能搜索
- 🚀 开箱即用 - Docker 一键部署,5分钟启动服务
- 📊 多数据源融合 - AKShare、Tushare、yFinance、Finnhub 智能聚合
- 🏛️ 宏观经济数据 - GDP、CPI、PMI、货币供应量等全面覆盖
- 🧪 快速测试工具 - 内置接口测试页面,可视化API调试
- 💾 高性能缓存 - Redis 加速 + 自动降级,稳定可靠
# 1. 克隆项目
git clone git@github.com: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
| 分类 | 接口 | 端点 | 描述 |
|---|---|---|---|
| 📊 行情数据 | Market Price | GET /stock/price |
历史价格+AI分析报告 |
| Stock Quote | GET /api/stock/news |
实时行情快照 | |
| Stock Quotes | POST /api/stock/quotes |
批量行情查询 | |
| 💼 基本面 | Fundamental | GET /api/stock/fundamental |
财务基本面数据 |
| 📰 新闻资讯 | Stock News | GET /api/stock/news |
最新股票新闻 |
| News by Date | GET /api/stock/news/date |
指定日期新闻 | |
| 🏛️ 宏观经济 | GDP Data | GET /api/macro/gdp |
GDP数据查询 |
| CPI Data | GET /api/macro/cpi |
CPI数据查询 | |
| PMI Data | GET /api/macro/pmi |
PMI数据查询 | |
| PPI Data | GET /api/macro/ppi |
PPI数据查询 | |
| Money Supply | GET /api/macro/money-supply |
货币供应量数据 | |
| LPR Data | GET /api/macro/lpr |
LPR利率数据 | |
| Social Financing | GET /api/macro/social-financing |
社会融资规模数据 | |
| 📅 交易日历 | Trading Days | GET /api/calendar/trading-days |
交易日列表 |
| Is Trading Day | GET /api/calendar/is-trading-day |
交易日检查 | |
| Trading Hours | GET /api/calendar/trading-hours |
交易时间信息 | |
| Exchanges | GET /api/calendar/supported-exchanges |
支持的交易所 |
💡 提示: 所有接口支持 A股、港股、美股三大市场
📚 详细文档: 启动后访问 http://localhost:9998/docs
🧪 快速测试: 访问 http://localhost:9998/ 使用可视化测试工具
|
|
# 【必填】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 # 新闻聚合📖 完整配置说明
| 配置项 | 说明 | 默认值 |
|---|---|---|
REDIS_HOST |
Redis 主机 | redis(Docker)/ localhost |
CACHE_ENABLED |
是否启用缓存 | true |
CACHE_TTL |
缓存过期时间(秒) | 3600 |
详见:配置指南
无需安装任何工具,直接在浏览器中测试所有API接口:
- 启动服务:
docker-compose up -d - 打开测试页面: http://localhost:9998/
- 选择接口: 从左侧面板选择要测试的API
- 填写参数: 自动填充常用参数,支持自定义修改
- 发送请求: 一键测试,实时查看响应结果
- 🎨 可视化界面 - 直观的API分类和参数表单
- 🔄 实时测试 - 即时发送请求并显示响应
- 🎯 参数预填 - 智能填充常用股票代码和日期
- 📝 结果高亮 - JSON响应自动格式化和语法高亮
- 📊 多接口支持 - 覆盖股票、宏观经济、交易日历所有接口
- 🌐 响应式设计 - 支持桌面和移动设备
🔹 股票数据测试
• 查询贵州茅台(600519)历史价格和技术分析
• 获取苹果(AAPL)实时行情快照
• 批量查询多只热门股票
🔹 宏观经济数据测试
• 查询最近5年GDP增长趋势
• 获取CPI、PPI通胀数据对比
• 分析货币供应量变化
🔹 交易日历测试
• 检查节假日是否为交易日
• 获取指定时间段的所有交易日
• 查询不同交易所的交易时间
启动服务后访问以下地址查看完整的 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) - 完整财务数据结构
1️⃣ 市场行情分析 - Market Price
- 路径:
GET /stock/price - 描述: 获取指定股票的历史价格数据及AI分析报告
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001, AAPL |
start_date |
string | 否 | 开始日期 | 2024-07-13 |
end_date |
string | 否 | 结束日期 | 2025-07-13 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
{
"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"2️⃣ 基本面数据 - Stock Fundamental
- 路径:
GET /api/stock/fundamental - 描述: 获取股票基本面财务数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000008, 600519 |
curr_date |
string | 否 | 查询日期 | 2025-06-01 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01" 3️⃣ 实时行情 - Stock Quote
- 路径:
GET /api/stock/news - 描述: 获取股票实时行情快照
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001, AAPL |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
{
"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" 4️⃣ 批量行情查询 - Stock Quotes
- 路径:
POST /api/stock/quotes - 描述: 批量查询多个股票的实时行情
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
symbols |
array | 是 | 股票代码列表 |
Authorization |
string | 否 | 认证令牌(Header) |
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"]}'5️⃣ 股票新闻 - Stock News
- 路径:
GET /api/stock/news - 描述: 获取指定股票的最新新闻
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001, AAPL |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/stock/news?symbol=000001"6️⃣ 指定日期新闻 - News by Date
- 路径:
GET /api/stock/news/date - 描述: 获取指定日期范围内的股票新闻
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001 |
target_date |
string | 是 | 目标日期 | 2025-09-10 |
days_before |
integer | 否 | 向前查询天数 | 7 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/stock/news/date?symbol=000001&target_date=2025-09-10&days_before=7"7️⃣ 交易日列表 - Trading Days
- 路径:
GET /api/calendar/trading-days - 描述: 获取指定时间范围内的交易日列表
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001 |
start_date |
string | 是 | 开始日期 | 2025-01-01 |
end_date |
string | 是 | 结束日期 | 2025-09-01 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/calendar/trading-days?symbol=000001&start_date=2025-01-01&end_date=2025-09-01" \8️⃣ 交易日检查 - Is Trading Day
- 路径:
GET /api/calendar/is-trading-day - 描述: 检查指定日期是否为交易日
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001 |
check_date |
string | 是 | 检查日期 | 2025-09-30 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=2025-09-30" \9️⃣ 交易时间 - Trading Hours
- 路径:
GET /api/calendar/trading-hours - 描述: 获取指定日期的交易时间信息
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
symbol |
string | 是 | 股票代码 | 000001 |
check_date |
string | 是 | 检查日期 | 2025-09-30 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/calendar/trading-hours?symbol=000001&check_date=2025-09-30" \🔟 支持的交易所 - Supported Exchanges
- 路径:
GET /api/calendar/supported-exchanges - 描述: 获取系统支持的所有交易所列表
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization |
string | 否 | 认证令牌(Header) |
{
"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" \1️⃣ GDP 数据 - GDP Data
- 路径:
GET /api/macro/gdp - 描述: 获取中国GDP数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
{
"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" \2️⃣ CPI 数据 - CPI Data
- 路径:
GET /api/macro/cpi - 描述: 获取中国CPI数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
{
"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" \3️⃣ PMI 数据 - PMI Data
- 路径:
GET /api/macro/pmi - 描述: 获取中国PMI数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/macro/pmi?start_date=2020-01-01&end_date=2024-12-31" \4️⃣ PPI 数据 - PPI Data
- 路径:
GET /api/macro/ppi - 描述: 获取中国PPI数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/macro/ppi?start_date=2020-01-01&end_date=2024-12-31" \5️⃣ 货币供应量 - Money Supply
- 路径:
GET /api/macro/money-supply - 描述: 获取中国货币供应量数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/macro/money-supply?start_date=2020-01-01&end_date=2024-12-31" \6️⃣ LPR 利率 - LPR Data
- 路径:
GET /api/macro/lpr - 描述: 获取中国LPR利率数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
curl -X GET "http://localhost:9998/api/macro/lpr?start_date=2020-01-01&end_date=2024-12-31" \7️⃣ 社会融资规模 - Social Financing
- 路径:
GET /api/macro/social-financing - 描述: 获取中国社会融资规模数据
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
start_date |
string | 否 | 开始日期 | 2020-01-01 |
end_date |
string | 否 | 结束日期 | 2024-12-31 |
Authorization |
string | 否 | 认证令牌(Header) | a7f3518b-... |
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遵循以下设计原则:
✅ 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个工作日内更新
- 新闻数据: 实时抓取,每小时刷新
| 端口 | 服务 | 说明 |
|---|---|---|
9998 |
FastAPI | RESTful API + Swagger 文档 |
9999 |
MCP Server | Model Context Protocol 服务 |
6379 |
Redis | 内部缓存(不对外暴露) |
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f stock-mcp
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
# 重新构建
docker-compose up -d --build❌ Redis 连接失败
# 检查配置
cat .env | grep REDIS_HOST
# 确保 Docker 环境使用: REDIS_HOST=redis
# 检查 Redis 状态
docker-compose ps redis❌ yFinance 超时
# 检查代理配置
cat .env | grep PROXY
# Docker 环境应使用: HTTP_PROXY=http://host.docker.internal:7890❌ Tushare 权限错误
确保 Token 有效且已配置到 .env 文件:
grep TUSHARE_TOKEN .env更多问题:完整故障排查指南
- 📡 完整 API 文档 - 所有接口详细说明、参数、示例
- 💡 API 使用示例 - 实际场景的代码示例
- 📖 使用指南 - 配置、部署、最佳实践
- 🔧 开发文档 - 架构设计、二次开发
- 🌐 OpenAPI 规范 - 标准API规范文件
- 💻 Swagger UI - 交互式API测试(服务启动后访问)
- ✨ 新增宏观经济数据接口 - 支持GDP、CPI、PMI、PPI、货币供应量、LPR、社会融资规模
- 🧪 内置API测试工具 - 可视化接口测试页面,支持所有API的快速测试
- 📊 数据监控面板 - 实时展示数据获取状态和性能指标
- 🚀 性能优化 - 改进缓存策略,提升数据查询速度
- 📚 文档完善 - 新增宏观数据说明和测试工具使用指南
- 🔄 架构重构 - 基于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-featureMIT License - 详见 LICENSE