shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

stock-mcp

基于Model Context Protocol的智能股票数据服务，提供A股/港股/美股的实时行情、基本面分析、新闻资讯和AI驱动的深度研究报告

article

README

🚀 📈 Stock MCP Server

Stock MCP Server 是一个基于 Model Context Protocol 的智能股票数据服务平台，能够一站式获取 A 股、港股、美股的实时数据，并提供 AI 驱动的深度分析，为投资者提供全面、准确、高效的股票信息服务。

🚀 快速开始

# 1. 克隆项目
git clone <your-repo-url> && cd stock-mcp

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

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

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

🎯 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"]}'

✨ 主要特性

  • 🌐 全球市场覆盖 - 一键接入 A 股、港股、美股数据。
  • 🤖 AI 智能分析 - 提供新闻情绪分析、深度研究报告、智能搜索等功能。
  • 🚀 开箱即用 - 通过 Docker 一键部署，5 分钟即可启动服务。
  • 📊 多数据源融合 - 智能聚合 AKShare、Tushare、yFinance、Finnhub 等多个数据源。
  • 💾 高性能缓存 - 采用 Redis 加速，并具备自动降级功能，稳定可靠。

📦 安装指南

核心配置（.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       # 新闻聚合
📖 完整配置说明

| 配置项 | 说明 | 默认值 | | --------------- | ------------------ | ------------------------------ | | REDIS_HOST | Redis 主机 | redis（Docker）/ localhost | | CACHE_ENABLED | 是否启用缓存 | true | | CACHE_TTL | 缓存过期时间（秒） | 3600 |

详见：配置指南

💻 使用示例

基础用法

# 查询茅台历史价格及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 -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

📚 详细文档

🔧 技术细节

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 | 指定日期新闻 | | 📅 交易日历 | 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。

数据查询能力

  • ✅ 实时行情 - 分钟级价格/成交量。
  • ✅ 历史数据 - K 线图、复权价格。
  • ✅ 财务报表 - 资产负债表、现金流。
  • ✅ 技术指标 - MACD、RSI、布林带。
  • ✅ 资金流向 - 主力资金、北向资金。

AI 增强

  • 🔍 智能搜索 - Tavily 语义搜索。
  • 📰 情绪分析 - 多源新闻聚合 + 评分。
  • 📈 深度研究 - AI 生成研究报告。
  • 💡 决策辅助 - 数据驱动的投资建议。
  • 🌐 多语言支持 - 中英文自动识别。

API 接口文档

交互式文档

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

  • Swagger UI: http://localhost:9998/docs
  • ReDoc: http://localhost:9998/redoc
股票数据接口
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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Market Price API

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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Stock Fundamental API

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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Stock Quote API

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"]}'

Stock Quotes API

新闻数据接口
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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Stock News API

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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

News by Date API

交易日历接口
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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Trading Days API

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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"
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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"
🔟 支持的交易所 - 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" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

Supported Exchanges API

认证说明

所有 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"

API 设计规范

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

🐳 Docker 部署

服务架构

| 端口 | 服务 | 说明 | | ------ | ---------- | --------------------------- | | 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

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

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE。

🙏 致谢

本项目基于以下优秀开源项目构建： MCP • FastAPI • AKShare • Tushare • yFinance • Tavily

⭐️ 如果对你有帮助，请给个 Star ⭐️

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端