Metadata-Version: 2.4
Name: mcp-markets
Version: 0.12.6
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-dotenv>=1.0
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

<h1 align="center">mcp-finance</h1>
<p align="center">
  <strong>MCP Server for Global Financial Markets</strong><br>
   29+ tools · 3 markets · Millisecond-level quotes
</p>

<p align="center">
  <a href="README.en.md">English</a> ·
  <a href="https://github.com/ojkkk/mcp-finance">GitHub</a> ·
  <a href="https://pypi.org/project/mcp-markets/">PyPI</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-blue?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/MCP-1.4+-purple" alt="MCP">
  <img src="https://img.shields.io/badge/version-0.9.6-orange" alt="v0.9.0">
  <img src="https://img.shields.io/badge/License-MIT-green" alt="MIT">
</p>

---

## ⚠️ 重要免责声明

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

### 数据与合规
- 数据来源于第三方公开接口与网页爬虫，**不作任何准确性、完整性、及时性的保证**
- **无自有数据源**，全部依赖第三方：
  - **easy-tdx** 依赖通达信公开 TCP 服务器，非官方 API
  - **AKShare** 受站点改版影响极大，接口随时可能失效
  - **yfinance** 依赖 Yahoo Finance 公开接口
  - **Tushare** 为第三方社区数据平台
- 数据**无合规授权**，个人非商用无问题，**企业商用存在明确版权与合规风险**

### 回测与决策
- 回测结果不代表未来表现，**历史收益不预示未来收益**
- 使用者应独立判断并承担投资风险，**作者不对任何投资损失负责**
- 回测功能仅供学习量化策略的基本概念，不构成交易建议

### 当前能力与局限

| 维度 | 已支持 | 仍缺失 |
|------|--------|--------|
| **策略** | 8 种预设 + 自定义组合策略(AND/OR) | 无深度学习/AI 策略 |
| **优化** | 网格扫描 + Optuna TPE 贝叶斯优化 | — |
| **验证** | Walk-Forward 样本外 + 蒙特卡洛稳健性 | 无交叉验证 |
| **滑点** | 固定百分比 / 固定点数 / bar_impact / volume_share | 无真实 tick 级模拟 |
| **手续费** | A股万分之三 + 港美股差异化费率 | 无 min 佣金 |
| **财务** | 19+核心指标(营收/净利润/EPS/ROE/ROA/毛利率/净利率/营收增长率/资产负债率/流动比率等)，5大分类(核心/盈利/成长/风险/营运)，历史明细(同花顺) | 无一致预期、盈利预测 |
| **高频数据** | A股 1/5/15/30/60 分钟 K 线 | 港美股无分钟数据 |
| **市场覆盖** | A股 / 港股 / 美股 / 国内期货 | 无期权/外汇/加密货币 |

> **结论**: 本工具定位为 AI 助手的金融数据学习工具，**无法满足专业量化需求**。

### 使用前提
- **本工具定位为 AI 助手的金融数据学习工具，非专业交易/投资平台**
- 任何依赖本工具数据做出的投资决策，风险自负
- **强烈建议仅用于学习 MCP 协议开发、数据分析练习等非商业场景**

---

## 简介

`mcp-finance` 是一个面向 AI 助手（Claude / Codex / Cursor 等 MCP 客户端）的金融数据服务，基于 **easy-tdx**（通达信毫秒级） + **Tushare**（财务数据） + **AKShare** + **yfinance** 四数据源，覆盖 **A股、港股、美股、期货**四大市场，提供行情、K线、技术指标、选股、回测、分析等 29 个工具。

---

## 安装

```bash
pip install mcp-markets
```

Python 3.10+，核心依赖：`easy-tdx` `akshare` `plotly` `backtrader` `pandas` `numpy` `pydantic`。

---

## 配置 MCP 客户端

### Claude Desktop

编辑 `claude_desktop_config.json`：

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

### Codex

```bash
codex mcp add mcp-finance -- python -m mcp_finance.server
```

### Cursor / VS Code

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

### 可选：启用 Tushare 财务数据

[Tushare](https://tushare.pro) 提供 PE/PB/ROE、季度财报等基本面数据。免费版需要注册并获取积分后才能使用。

```bash
# 注册 https://tushare.pro → 获取 token → 设置环境变量
export TUSHARE_TOKEN=你的token   # Linux / Mac
set TUSHARE_TOKEN=你的token       # Windows CMD
$env:TUSHARE_TOKEN="你的token"    # Windows PowerShell
```

或在 MCP 客户端配置中传入：

```json
{
  "mcpServers": {
    "mcp-finance": {
      "command": "python",
      "args": ["-m", "mcp_finance.server"],
      "env": { "TUSHARE_TOKEN": "你的token" }
    }
  }
}
```

未设置或积分不足时，系统自动降级使用 AKShare / easy-tdx，不影响基础功能。

---

## 全部工具 (29)

### 行情
| 工具 | 说明 | 覆盖 |
|------|------|------|
| `get_realtime_quote` | 单股实时行情 | A股/港股/美股/期货 |
| `batch_quotes` | 批量行情查询 | A股/港股/美股 |
| `get_market_indices` | 大盘指数 | 上证/深证/恒生/道琼斯等 |
| `get_futures_list` | 期货主力合约列表 | 国内商品+股指期货 |
| `search_stock` | 股票搜索（本地毫秒级） | A股/港股/美股 |

### K线
| 工具 | 说明 | 覆盖 |
|------|------|------|
| `get_kline` | 日/周/月K线，支持前/后复权 | A股/港股/美股/期货 |
| `get_minute_kline` | 分钟K线（1/5/15/30/60分钟） | 仅A股 |

### 技术分析
| 工具 | 说明 |
|------|------|
| `get_technical_indicators` | MA/MACD/KDJ/RSI/BOLL/WR/BIAS + 金叉死叉/超买超卖信号 |
| `plot_kline` | 交互式K线图（蜡烛图+均线+MACD/KDJ/RSI副图） |
| `comparison_chart` | 多股走势对比图（归一化） |

### 财务与市场
| 工具 | 说明 |
|------|------|
| `get_financials` | 结构化财务数据：5类19+指标(营收/净利润/EPS/ROE/ROA/毛利率/净利率/营收增长率/资产负债率/流动比率等)+历史明细 |
| `get_sector_ranking` | 行业/概念板块涨幅排行 |
| `get_north_flow` | 北向/南向资金流向 |
| `get_dragon_tiger` | 龙虎榜每日明细 |
| `get_block_trades` | 大宗交易明细 |
| `get_margin_trading` | 融资融券数据 |

### 资金与机构
| 工具 | 说明 |
|------|------|
| `get_fund_flow` | 主力净流入（easy-tdx 实时） |
| `get_institutional_holdings` | 十大流通股东 |

### 宏观与研报
| 工具 | 说明 |
|------|------|
| `get_macro_data` | GDP / CPI / PMI / 货币供应量 / 外汇储备 |
| `get_research_reports` | 个股研报（机构评级/盈利预测） |

### 选股
| 工具 | 说明 |
|------|------|
| `stock_screener` | 全市场条件筛选（涨跌幅/量比/PE/PB/ROE等） |
| `factor_screener` | 五因子打分排名（动量/价值/质量/增长/波动） |

### 回测
| 工具 | 说明 |
|------|------|
| `backtest_strategy` | 8种策略回测（双均线/MACD/RSI/KDJ/BOLL/海龟/波动率/均值回归） |
| `optimize_strategy` | 参数网格扫描优化 |
| `portfolio_backtest` | 多股组合回测（支持自定义权重） |

### 分析
| 工具 | 说明 |
|------|------|
| `analyze_stock` | 综合评分（行情+技术+财务+均线 0-100分） |
| `compare_stocks` | 多股横向对比排名 |
| `correlation_matrix` | 相关性矩阵 + 低相关配对 |

### 系统
| 工具 | 说明 |
|------|------|
| `test_data_sources` | 诊断所有数据源可用性 |

---

## 使用示例

| 场景 | 对话示例 |
|------|----------|
| 查行情 | "茅台(600519)现在什么价？" |
| 画K线 | "画一张茅台120天日K线图，带上MACD和RSI" |
| 技术分析 | "分析比亚迪的技术指标，有没有金叉信号？" |
| 看资金 | "茅台今天主力净流入多少？" |
| 条件选股 | "涨超3%、量比>1.5、换手率>5%、PE<30的股票" |
| 多因子 | "五因子打分排名前20的A股" |
| 策略回测 | "双均线(5,20)回测美的集团2024年全年" |
| 参数优化 | "找美的集团双均线最优参数" |
| 投资组合 | "茅台+宁德+招行等权组合回测近一年" |
| 个股分析 | "给我一份茅台的综合分析报告" |
| 多股对比 | "对比茅台、五粮液、老窖、汾酒" |
| 相关性 | "茅台和五粮液的相关性？" |
| 宏观数据 | "最近一年CPI数据" |
| 看研报 | "茅台最新机构研报" |
| 港股美股 | "腾讯港股 / 苹果股票 什么价？" |

---


---

## Web Dashboard

`mcp-finance` 内置了一个本地 Web 界面，将 MCP Tools 的能力包装为可视化面板。

### 启动方式

```bash
# 方式一：双击项目根目录的脚本（推荐，自动杀旧进程）
start_dashboard.bat          # Windows

# 方式二：命令行启动
mcp-dashboard                # 默认 http://localhost:8080
mcp-dashboard 3000           # 指定端口

# 方式三：直接运行模块
python -m mcp_finance.dashboard.app
```

> 服务基于 Flask 提供，启动后浏览器访问 `http://localhost:8080`。

### 功能页面

| 页面 | 路径 | 说明 |
|------|------|------|
| **行情总览** | `/` | 大盘指数、热门股票、行业板块排行、北向资金、个股K线速查、股票搜索 |
| **选股器** | `/screener` | 多因子排行（综合评分+动量+价值+质量+增长+波动）+ 条件选股（涨跌幅/换手率/量比/PE/PB/市值/ROE） |
| **策略回测** | `/backtest` | 基础回测 + 参数优化（网格/贝叶斯）+ Walk-Forward 样本外验证 + 蒙特卡洛稳健性检验 |

### 技术栈

- **后端**：Flask（前后端数据格式兼容，不额外包层）
- **数据源**：easy-tdx（毫秒级行情）+ AKShare（财务/板块/北向资金）+ yfinance（港美股兜底）+ Tushare（日线补充，需 Token）
- **图表**：Plotly 交互式 K 线图 + 回测权益曲线
- **UI**：响应式设计，深色主题

## 数据源

| 数据源 | 说明 | 延迟 | 合规性 |
|--------|------|------|--------|
| **easy-tdx** | 通达信 TCP 直连，主力行情/K线/资金流向 | 毫秒级 | ⚠️ 协议逆向，仅供学习 |
| **Tushare** | PE/PB/ROE/季度财报，Token 鉴权（可选，需积分） | 免费版延迟15分钟 | ✅ Token 鉴权 |
| **AKShare** | 新浪/同花顺/东方财富，板块/龙虎榜/研报 | 秒级 | ⚠️ 网页爬虫，仅供学习 |
| **yfinance** | Yahoo Finance，港股美股兜底 | 秒级 | ⚠️ 非官方接口 |

---

## 项目结构

```
mcp_finance/
  server.py           MCP 路由与工具注册
  api.py              三数据源封装层
  api_extended.py      分钟K线 / 资金流向 / 机构持仓 / 宏观 / 研报
  analysis.py          综合评分 / 多因子选股 / 多股对比
  portfolio.py         组合回测 / 相关性矩阵
  indicators.py        9大技术指标 + 信号识别
  backtest.py          Backtrader 回测引擎
  chart.py             Plotly 交互式图表 / 对比图
  screener.py          全市场选股器
  cache.py             TTL 内存+磁盘缓存
  validators.py        Pydantic 参数校验
  errors.py            统一错误处理
  logging_config.py    日志配置
tests/
  test_indicators.py   指标单元测试
  test_screener.py     选股器单元测试
```

---

## 开发

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

---

---

## 局限与潜在风险

### 数据源的天然短板

- **无自有数据源**：全部依赖第三方公开接口与网页爬虫。TDX 依赖通达信公开服务器，AKShare 受站点改版影响极大，接口随时可能失效
- **无合规授权**：数据无官方商业授权，个人学习非商用无问题，**企业商用存在明确版权风险**
- **Tushare 需要积分**：免费注册后需通过贡献赚取积分才能调用 API，详见 [Tushare 积分规则](https://tushare.pro/document/1?doc_id=13)

### 专业深度不足

- **财务数据**：覆盖 19+ 核心指标（营收/净利润/EPS/ROE/ROA/毛利率/净利率/营收增长率/资产负债率/流动比率等），分5大类结构化返回。仍缺失明细财报（三表）、一致预期、盈利预测等高阶基本面数据
- **高频数据**：分钟 K 线仅支持 A 股，港美股无高频数据
- **回测能力**：偏入门级别，仅 8 种预设策略，参数优化为简单网格扫描，不支持自定义复杂策略、滑点/手续费精细化模拟，无法满足专业量化需求

### 免责重申

> **本工具仅供学习交流，所有数据仅供参考。投资有风险，入市需谨慎。作者不对任何因使用本工具产生的投资损失承担责任。**

---

## License

MIT

