Metadata-Version: 2.4
Name: stockhub-mcp
Version: 0.4.1
Summary: StockHub MCP — 43-tool financial market data server for A-shares, HK stocks, US equities, funds, ETFs, futures, indices. Multi-source fallback: yfinance, efinance, Tencent, Sina, EastMoney, AkShare.
License: MIT
Project-URL: Homepage, https://github.com/TimWu0101/stockhub-mcp
Project-URL: Repository, https://github.com/TimWu0101/stockhub-mcp
Keywords: mcp,stock,finance,trading,quantitative,A-share,美股,港股
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: yfinance>=0.2.40
Requires-Dist: pandas>=2.2.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: cachetools>=5.3.0
Requires-Dist: akshare>=1.14.0
Requires-Dist: pandas-market-calendars>=4.4.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: enhanced
Requires-Dist: efinance>=1.0.0; extra == "enhanced"

# StockHub MCP

> 零配置、免费、43 工具的金融数据 MCP 服务器 —— A 股/港股/美股/基金/ETF/期货/指数，多源自动降级，为 AI 应用提供统一行情与分析接口。

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-v0.4.0-blue)](https://pypi.org/project/stockhub-mcp/)
[![Tools](https://img.shields.io/badge/tools-43-orange)](https://github.com/TimWu0101/stockhub-mcp/blob/main/docs/TOOLS.md)

---

## 为什么选 StockHub

| 特色 | 其他 MCP | StockHub |
|---|---|---|
| 配置要求 | 要配 API Key | **零配置可用**，6 源自动 fallback |
| 市场覆盖 | 单市场（美股为主） | **三市场统一**，A 股/港股/美股一套 schema |
| 技术分析 | 只给数字 | **智能定性**：7 档趋势 + 5 档量能 + 综合评分 |
| 风险分析 | 无或需付费 | **纯本地计算**：波动率/夏普/回撤/VaR/Beta/相关性矩阵 |
| AI 调用效率 | 一个请求一个指标 | **Pipeline 一键组合**：1 次调用 = 行情 + 6 指标 + 定性 |

---

## 能做什么

| 类别 | 能力 |
|---|---|
| 📈 实时行情 | A 股/港股/美股实时报价、批量查询 [→工具](./docs/TOOLS.md#行情类) |
| 📊 历史数据 | 多周期 K 线（日/周/月），前复权/后复权 [→工具](./docs/TOOLS.md#历史类) |
| 🔬 技术分析 | MA/MACD/RSI/KDJ/布林带 + 智能定性判断 [→工具](./docs/TOOLS.md#技术分析) |
| 🏭 板块资金 | 行业板块/概念板块涨跌、市场资金流向 [→工具](./docs/TOOLS.md#A股特色) |
| 🀄 A 股特色 | 龙虎榜、涨跌停、停牌查询、南/北向资金 [→工具](./docs/TOOLS.md#A股特色) |
| 💰 基金 ETF | 净值查询、历史净值、排名、ETF 详情 [→工具](./docs/TOOLS.md#基金ETF) |
| 📋 研究估值 | PE/PB/PS/PEG、ROE、财务三表、历史分位 [→工具](./docs/TOOLS.md#研究估值) |
| 📉 组合风险 | 相关性矩阵、组合暴露分析、波动率/夏普/VaR [→工具](./docs/TOOLS.md#组合风险) |
| 🏛️ 指数期权 | 指数行情/对比、期权链（美股）、分析师预测 [→工具](./docs/TOOLS.md#指数期权) |

[完整 43 工具列表 →](./docs/TOOLS.md)

## 数据源架构

**当前使用的数据源与默认角色：**

> 并非所有工具都走相同 fallback 链路。

```
efinance → 东方财富 → 腾讯 → 新浪 → yfinance → AkShare
  (A股增强)   (主要)    (行情)   (备源)   (美股/港股)   (兜底)
```

| 市场 | 数据源 | 免配置 |
|---|---|---|
| 🇨🇳 A 股 | efinance、东方财富、腾讯、新浪 | ✅ |
| 🇭🇰 港股 | 腾讯、yfinance | ✅ |
| 🇺🇸 美股 | yfinance | ✅ |
| 💰 基金/ETF | 东方财富 | ✅ |
| 🛢️ 期货 | AkShare | ✅ |

---

## 快速开始

### 使用者

```bash
pip install stockhub-mcp

# 可选：A 股龙虎榜/资金流更稳定
pip install efinance
```

```json
{
  "mcpServers": {
    "stockhub": {
      "command": "fastmcp",
      "args": ["run", "-m", "stockhub_mcp.server"]
    }
  }
}
```

### 开发者

```bash
git clone https://github.com/TimWu0101/stockhub-mcp.git
cd stockhub-mcp
pip install -e .
fastmcp run src/stockhub_mcp/server.py:mcp
```

---

## 使用示例

### 一键 Pipeline 分析

```
→ 快速分析下贵州茅台

← 贵州茅台 ¥1,215.00 跌 -2.02%
   趋势：空头排列 | MACD 死叉 | RSI 超卖(17.25)反弹信号
   阻力：MA5=1,254.74 | 偏离 -3.17%
   信号：卖出(10分) | 量能：正常
```
*一个调用 = 行情 + MA/MACD/RSI/KDJ/BOLL + 趋势定性 + 信号评分*

### 组合相关性矩阵

```
→ 茅台、五粮液、招行、美的四只票相关性怎么样

← 茅台↔五粮液 0.77(高度同步) | 招行↔美的 0.28(最佳分散)
```
*4 只标的，32 次历史查询并行完成，无需任何外部 API*

### 一键风险报告

```
→ 茅台过去一年风险多大

← 年化波动 20.05% | 最大回撤 -21.86%
   夏普比率 -0.83 | 日 VaR(95%) -1.75%
```
*纯 numpy 本地计算，不依赖任何外部服务*

### 技术面深度诊断

```
→ 茅台技术面什么状态

← 空头排列，价格低于全部均线
   MACD 死叉，DIF=-28.22 DIF <- DEA=-26.85
   RSI6=17.25 极度超卖，RSI14=21.17
   KDJ J=-3.02 罕见负值钝化
   跌破布林下轨 1,226.79 → 1215 进入超跌区域
   综合评分：10/100 卖出信号
```
*7 指标联动分析 + 定性判断，不只是数值输出*

### 龙虎榜监控

```
→ 最近龙虎榜有哪些游资动向

← 100 只上榜，净买入前 3：中钨高新 +6.39 亿、铂力特涨停、天和磁材+2.54 亿
   净卖出前 3：光迅科技 -0.97 亿、兆易创新、宁波华翔
```

### Beta 对标大盘

```
→ 苹果相对标普500的Beta是多少

← 年化波动 22.59% | Beta=0.89 | 夏普 1.78 | 最大回撤 -13.82%
   波动略低于大盘，防御性特征明显
```
*纯本地计算，同一工具同时返回波动率/夏普/VaR/Beta*

### 组合诊断

```
→ 分析下 AAPL TSLA NVDA MSFT GOOGL 这个组合

← 5 只，分散度良好 | 组合波动 16.25% | 平均相关性 0.27
   个股波动：TSLA 39.51% > NVDA 37.53% > MSFT 31.94% > GOOGL 29.71% > AAPL 23.63%
   年化收益：GOOGL +41.41% > NVDA +38.17% > AAPL +20.26% > MSFT -45.48% > TSLA -29.78%
```
*一键组合诊断：集中度 + 组合波动 + 个股风险收益 + 平均相关性*

### 多市场统一查询

```
→ 对比腾讯(港股)和苹果(美股)的估值

← 腾讯：PE=22.4 / PB=5.2 / 股息率=0.3%
   苹果：PE=32.1 / PB=38.5 / 股息率=0.46%
```
*同一工具、同一 schema，不切换数据源*

---

## 架构

```
stockhub_mcp/
├── server.py          # FastMCP 入口，43 工具注册
├── domain/            # 领域层：符号解析、响应构建、交易时段
├── models/            # 17 个 Pydantic 数据模型
├── services/          # 6 个数据源 + 路由 + 熔断 + 缓存
├── tools/             # 17 个工具实现模块
└── core/              # Pipeline 流水线引擎
```

## 文档

- [完整工具列表](./docs/TOOLS.md)
- [Schema 参考](./docs/design/schema-reference.md)
- [路线图](./docs/tracking/roadmap.md)
- [CHANGELOG](./CHANGELOG.md)

## 免责声明

⚠️ 数据来自公开免费接口，不保证实时性、完整性和准确性。本项目不构成任何投资建议。

## 许可证

MIT
