Metadata-Version: 2.4
Name: mcp-markets
Version: 0.12.9
Summary: 全市场金融数据 MCP Server — A股/港股/美股/期货 行情/K线/技术指标/选股/回测 基于 easy-tdx + AKShare + yfinance 三数据源
Project-URL: homepage, https://github.com/ojkkk/mcp-finance
Project-URL: repository, https://github.com/ojkkk/mcp-finance
Project-URL: issues, https://github.com/ojkkk/mcp-finance/issues
Author-email: mcp-markets <mcp-finance@github.com>
License: MIT
License-File: LICENSE
Keywords: a-share,akshare,backtest,backtrader,easy-tdx,finance,futures,hk-stock,mcp,stock,technical-analysis,tushare,us-stock,yfinance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Requires-Dist: akshare>=1.18
Requires-Dist: backtrader>=1.9
Requires-Dist: easy-tdx>=1.14
Requires-Dist: flask>=3.0
Requires-Dist: mcp>=1.4.1
Requires-Dist: numpy>=1.23
Requires-Dist: optuna>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: plotly>=5.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: python-dotenv>=1.0
Requires-Dist: scipy>=1.10
Requires-Dist: tushare>=1.4
Requires-Dist: yfinance>=0.2.0
Provides-Extra: all
Requires-Dist: pytest-mock>=3.14; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<!-- 🌊 顶部动态波浪 + 大标题（服务端渲染，GitHub 兼容） -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4F46E5,20:0EA5E9,50:8B5CF6,80:EC4899,100:4F46E5&height=200&section=header&text=mcp-finance&fontSize=52&fontColor=ffffff&fontAlignY=38&desc=%E5%85%A8%E5%B8%82%E5%9C%BA%E9%87%91%E8%9E%8D%E6%95%B0%E6%8D%AE%20MCP%20Server&descSize=18&descColor=c4b5fd&descAlignY=68" width="100%">

<!-- 📝 动态打字副标题：轮播核心卖点 -->
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=18&pause=900&color=6366F1&center=true&vCenter=true&width=620&lines=AI+%E5%8A%A9%E6%89%8B%E7%9C%8B%E6%87%82+A%E8%82%A1+%C2%B7+%E6%B8%AF%E8%82%A1+%C2%B7+%E7%BE%8E%E8%82%A1+%C2%B7+%E6%9C%9F%E8%B4%A7;31+%E4%B8%AA+MCP+%E5%B7%A5%E5%85%B7+%C2%B7+4+%E5%A4%A7%E6%95%B0%E6%8D%AE%E6%BA%90;9+%E7%A7%8D%E7%AD%96%E7%95%A5%E5%9B%9E%E6%B5%8B+%C2%B7+%E8%B4%9D%E5%8F%B6%E6%96%AF%E4%BC%98%E5%8C%96+%C2%B7+%E9%98%B2%E8%BF%87%E6%8B%9F;%E6%AF%AB%E7%A7%92%E7%BA%A7%E8%A1%8C%E6%83%85+%C2%B7+%E4%BA%A4%E4%BA%92%E5%BC%8FK%E7%BA%BF+%C2%B7+Web+%E7%9C%8B%E6%9D%BF" alt="tagline">

<br>

<!-- 🔵 徽章行 -->
<a href="https://pypi.org/project/mcp-markets/"><img src="https://img.shields.io/pypi/v/mcp-markets?color=4F46E5&logo=pypi&logoColor=fff&style=flat-square" alt="PyPI Version"></a>
<a href="https://pypi.org/project/mcp-markets/"><img src="https://img.shields.io/pypi/dm/mcp-markets?color=0EA5E9&logo=pypi&logoColor=fff&style=flat-square" alt="Downloads"></a>
<a href="https://github.com/ojkkk/mcp-finance"><img src="https://img.shields.io/github/stars/ojkkk/mcp-finance?style=flat-square&color=FB923C" alt="Stars"></a>
<img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=FBD34A&style=flat-square" alt="Python">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="MIT License"></a>

<br>

<!-- 📦 能力标签 -->
<img src="https://img.shields.io/badge/Tools-31-8B5CF6?style=flat-square" alt="31 Tools">
<img src="https://img.shields.io/badge/A%E8%82%A1-%E2%9C%93-EF4444?style=flat-square" alt="A Shares">
<img src="https://img.shields.io/badge/%E6%B8%AF%E8%82%A1-%E2%9C%93-F97316?style=flat-square" alt="HK">
<img src="https://img.shields.io/badge/%E7%BE%8E%E8%82%A1-%E2%9C%93-3B82F6?style=flat-square" alt="US">
<img src="https://img.shields.io/badge/%E6%9C%9F%E8%B4%A7-%E2%9C%93-14B8A6?style=flat-square" alt="Futures">

</div>

---

## ⚡ 快速开始

```bash
pip install mcp-markets

# 方式一：作为 MCP Server 运行（供 Claude / Codex / Cursor 调用）
python -m mcp_finance.server

# 方式二：启动内置 Web Dashboard
mcp-dashboard              # 默认 http://localhost:8080
```

> Python 3.10+ · 零配置即可使用 · 可选设置 `TUSHARE_TOKEN` 环境变量启用高级财务数据

---

## ✨ 核心能力一览

| 模块 | 功能 | 亮点 |
|------|------|------|
| 📈 **实时行情** | A股/港股/美股/期货/指数 | easy-tdx 毫秒级，三源自动降级 |
| 📊 **K线数据** | 日/周/月/分钟 K线，前/后复权 | A股 800 条，港美股 yfinance 兜底 |
| 🔬 **技术指标** | MA·MACD·KDJ·RSI·BOLL·WR·BIAS | 金叉/死叉/超买超卖自动识别 |
| 🔍 **选股器** | 11 维条件筛选 + 五因子排名 | 动量·价值·质量·增长·波动 |
| 🧪 **策略回测** | 9 大策略 + 参数优化 | Backtrader 事件驱动，125× 性能提升 |
| 💼 **组合分析** | 多股对比 + 相关性矩阵 + 组合回测 | 支持等权/自定义权重 |
| 🏢 **基本面** | 财务指标 / 机构持仓 / 研报 / 龙虎榜 | AKShare + Tushare 双源 |
| 🖥️ **Web 看板** | Flask 实时行情 Dashboard | Plotly + ECharts 交互图表 |

---

## 🏗️ 四数据源架构

```mermaid
graph LR
    A["📡 数据源层"] --> B["⚡ easy-tdx<br/>通达信 TCP · <50ms"]
    A --> C["🌐 AKShare<br/>新浪 / 同花顺 / 东方财富"]
    A --> D["🌍 yfinance<br/>Yahoo Finance 兜底"]
    A --> E["📈 Tushare<br/>深度财务 · Token 鉴权"]

    B --> F["🔧 31 MCP Tools"]
    C --> F
    D --> F
    E --> F

    F --> G["📈 行情<br/>实时价 / 批量 / K线"]
    F --> H["🔬 技术分析<br/>MA·MACD·KDJ·RSI·BOLL"]
    F --> I["📋 选股<br/>条件筛选 · 五因子排名"]
    F --> J["⚙️ 回测<br/>9 策略 · 贝叶斯优化"]
    F --> K["📊 组合<br/>多股对比 · 相关性 · Portfolio"]
    F --> L["🏢 基本面<br/>财务 · 研报 · 龙虎榜 · 大宗"]
    F --> M["🖥️ Dashboard<br/>Flask Web · 实时刷新"]

    style A fill:#1e1b4b,stroke:#6366f1,color:#fff
    style F fill:#0f172a,stroke:#334155,color:#fff
    style G fill:#312e81,color:#fff
    style H fill:#312e81,color:#fff
    style I fill:#312e81,color:#fff
    style J fill:#312e81,color:#fff
    style K fill:#312e81,color:#fff
    style L fill:#312e81,color:#fff
    style M fill:#be185d,color:#fff
```

---

## 🎯 全部 31 个 MCP 工具

### 行情报价

| 工具 | 功能 | 数据源 | 延迟 |
|------|------|--------|------|
| `get_realtime_quote` | 单股实时行情（现价/涨跌幅/量比/换手率） | easy-tdx → AKShare → yfinance | < 100ms |
| `batch_quotes` | 批量查询多只股票行情 | easy-tdx | < 1s / batch |
| `get_kline` | 日/周/月 K线 + 前/后复权 | easy-tdx (A股) / AKShare+yfinance (港美股) | < 500ms |
| `get_minute_kline` | 1/5/15/30/60 分钟 K线（仅 A股） | easy-tdx | < 200ms |
| `get_market_indices` | A股 / 港股 / 美股 大盘指数 | easy-tdx → AKShare | < 500ms |
| `get_futures_list` | 国内期货主力合约行情 | AKShare 新浪 | ~1s |
| `search_stock` | 代码/名称模糊搜索 | 本地映射 | 即时 |

### 技术分析

| 工具 | 功能 |
|------|------|
| `get_technical_indicators` | MA·MACD·KDJ·RSI·BOLL·WR·BIAS + 金叉/死叉/超买超卖/均线排列自动识别 |
| `plot_kline` | 交互式 K线 HTML（蜡烛图+均线+成交量+MACD/KDJ/RSI 副图） |

### 选股 & 分析

| 工具 | 功能 |
|------|------|
| `stock_screener` | 11 维条件选股（涨跌幅/量比/换手率/PE/PB/ROE/市值…） |
| `factor_screener` | 五因子综合打分排名（动量·价值·质量·增长·波动） |
| `analyze_stock` | 一站式个股分析报告（行情+技术+财务+综合评分 0-100） |
| `compare_stocks` | 多股横向对比，按评分排名 |
| `correlation_matrix` | 收益率相关性矩阵（辅助分散投资） |

### 回测 & 优化

| 工具 | 功能 | 策略 |
|------|------|------|
| `backtest_strategy` | 个股策略回测 | 双均线·MACD·RSI·KDJ·BOLL·海龟·波动率趋势·均值回归·自定义组合 |
| `optimize_strategy` | 网格扫描 / Optuna TPE 贝叶斯优化 | 自动剪枝 + 参数重要性分析 |
| `portfolio_backtest` | 多股组合回测 | 自定义权重 / 等权分配 |

### 市场数据

| 工具 | 功能 |
|------|------|
| `get_sector_ranking` | 行业/概念/地域板块涨跌排行 |
| `get_north_flow` | 北向/南向资金流向 |
| `get_fund_flow` | 个股主力资金净流入（easy-tdx 毫秒级） |
| `get_dragon_tiger` | 龙虎榜（营业部买卖明细） |
| `get_block_trades` | 大宗交易明细 |
| `get_margin_trading` | 融资融券数据 |
| `get_macro_data` | 中国宏观经济（GDP/CPI/PMI/M2/外汇储备） |

### 基本面

| 工具 | 功能 |
|------|------|
| `get_financials` | 5 大类 19+ 指标（核心/盈利/成长/风险/营运） |
| `get_institutional_holdings` | 十大流通股东 / 机构持仓 |
| `get_research_reports` | 机构研报（评级+目标价） |
| `comparison_chart` | 多股走势对比图（归一化交互 HTML） |
| `test_data_sources` | 一键诊断所有数据源可用性 |

---

## 🖥️ Web Dashboard

内置 Flask Web 界面，可视化所有 MCP 工具能力。

```bash
mcp-dashboard              # http://localhost:8080
mcp-dashboard 3000         # 指定端口
# 或双击 start_dashboard.bat（Windows）
```

| 页面 | 路由 | 功能 |
|------|------|------|
| **行情总览** | `/` | 大盘指数 · 热门股票 · 板块排行 · 北向资金 · K线速查 · 股票搜索 |
| **选股器** | `/screener` | 五因子排名 · 条件选股（11维）· 实时筛选 |
| **策略回测** | /backtest | 9 策略回测 · 网格/贝叶斯优化 · Walk-Forward · 蒙特卡洛（仅 Dashboard 提供） |

> 响应式布局 · Plotly / ECharts 交互图表 · 实时行情自动刷新

---

## 🔌 配置 MCP 客户端

<details>
<summary><b>Claude Desktop</b></summary>

```json
{
  "mcpServers": {
    "mcp-finance": {
      "command": "python",
      "args": ["-m", "mcp_finance.server"]
    }
  }
}
```
</details>

<details>
<summary><b>Codex</b></summary>

```bash
codex mcp add mcp-finance -- python -m mcp_finance.server
```
</details>

<details>
<summary><b>Cursor / VS Code</b></summary>

```json
{
  "mcpServers": {
    "mcp-finance": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_finance.server"]
    }
  }
}
```
</details>

> **可选：启用 Tushare 财务数据** — 设置环境变量 `TUSHARE_TOKEN=你的token`（注册 [tushare.pro](https://tushare.pro) 免费获取）。未设置时自动降级，不影响基础功能。

---

## 🧪 测试 & 开发

```bash
git clone https://github.com/ojkkk/mcp-finance.git
cd mcp-finance
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 代码检查
ruff check mcp_finance/
```

---

## 🌟 AI 对话示例

| 场景 | 自然语言提问 |
|------|------------|
| 行情 | "茅台现在什么价？" / "腾讯港股和苹果美股今天表现如何？" |
| 技术分析 | "茅台 MACD 金叉了吗？RSI 到什么位置了？" |
| 选股 | "找涨超 3%、量比>1.5、PE<30 的股票" / "五因子排名前 20" |
| 回测 | "双均线(5,20)回测茅台 2024 年全年" / "找茅台最优 MACD 参数" |
| 组合 | "茅台+宁德+招行等权组合回测近一年" |
| 分析 | "给我茅台的综合分析报告" / "对比茅台、五粮液、老窖" |
| 市场 | "最近 CPI 数据" / "北向资金最近在买什么？" |
| 研报 | "看看机构对茅台的最新评级" |

---

## ⚠️ 免责声明

> **本工具仅供学习交流，所有数据仅供参考，不构成任何投资建议。**

- 数据来源于第三方公开接口与网页爬虫，**不作准确性、完整性、及时性保证**
- **无自有数据源**，全部依赖 easy-tdx（通达信公开 TCP）/ AKShare（网页爬虫）/ yfinance / Tushare
- 数据**无合规商业授权**，个人非商用无问题，**企业商用存在版权与合规风险**
- 回测结果不代表未来表现，**历史收益不预示未来收益**
- **作者不对任何投资损失承担责任** · 投资有风险，入市需谨慎

---

## 📄 License

MIT © [mcp-finance](https://github.com/ojkkk/mcp-finance)

<!-- 🌊 底部波浪 -->
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4F46E5,50:8B5CF6,100:EC4899&height=100&section=footer&fontSize=0" width="100%">
</div>
