# 🇨🇳 AKShare MCP Server

> 给 Claude Code 装上 A 股数据能力。零 C 依赖，纯 Python + requests，双源融合（新浪 + 东方财富）。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)

## 为什么不用 AKShare？

AKShare 功能强大但依赖 numpy/pandas + cryptography（需要 Rust 编译），在 Python 3.13 上安装困难。本项目直接调用新浪财经和东方财富的公开 HTTP API，**零 C 依赖、秒装**。

## 快速开始

```bash
git clone https://github.com/YOUR_USERNAME/akshare-mcp.git
cd akshare-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install requests
```

## 配置 Claude Code

```json
{
  "mcpServers": {
    "akshare": {
      "command": "/path/to/akshare-mcp/.venv/bin/python",
      "args": ["/path/to/akshare-mcp/server.py"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}
```

> 如果网络能直连，去掉 `env` 字段。如果使用 Clash，建议添加 `DOMAIN-SUFFIX,eastmoney.com,DIRECT` 规则。

## 工具列表

| 分类 | 工具 | 描述 | 状态 |
|------|------|------|------|
| 🔭 大盘 | `market_overview` | 上证/深证/创业板/科创50/沪深300 实时行情 | ✅ |
| 📈 个股 | `stock_spot` | 个股实时行情 | ✅ |
| | `stock_history` | 历史K线（日/周/月） | ⚠️ push2his 代理不稳 |
| | `quick_analysis` | 行情+30日走势一键速览 | ⚠️ 实时部分OK，走势部分同上 |
| 📊 ETF | `etf_spot` | 主要宽基+行业ETF行情 | ✅ |
| | `etf_history` | ETF历史净值 | ⚠️ 同上 |
| 💰 资金 | `north_bound_flow` | 北向累计+南向每日 | ✅ |
| 🏭 板块 | `sector_detail` | 板块成分股列表 | ❌ 东财报表已下线 |
| 🐉 龙虎榜 | `dragon_tiger` | 上榜个股及净买入（自动T+1回退） | ✅ |
| | `dragon_tiger_seats` | 席位明细（机构/游资/散户拆分） | ✅ |
| | `dragon_tiger_summary` | 机构/游资/北向/散户汇总+情绪判断 | ✅ |
| 📰 公告 | `stock_announcements` | 个股最新公告（精准过滤） | ✅ |
| 📋 新闻 | `financial_news` | A股财经新闻（新浪API，支持关键词） | ✅ |
| 🎯 情绪 | `market_breadth` | 涨跌停统计+ETF情绪+综合情绪 | ✅ |
| | `margin_trading` | 融资余额/买入额 | ❌ 东财报表已下线 |
| | `institution_visits` | 机构调研记录 | ✅ |
| | `guba_hot` | 股吧热门帖子（散户情绪代理） | ❌ 股吧接口已废弃 |

## 使用示例

```
"今天大盘怎么样"              → market_overview
"茅台现在多少钱"              → stock_spot 600519
"帮我快速看看宁德时代"         → quick_analysis 300750
"沪深300有哪些ETF"            → etf_spot 沪深300
"北向资金最近在干嘛"           → north_bound_flow 10
"半导体板块有哪些票"           → sector_detail 半导体
"茅台年报"                    → stock_announcements 600519 keyword=年报
"今天龙虎榜"                  → dragon_tiger
```

## 数据源

| 数据 | 来源 | 延迟 | 备注 |
|------|------|------|------|
| 实时行情/指数/ETF | 新浪财经 `hq.sinajs.cn` | ~3秒 | 主力数据源 |
| 历史K线 | 东方财富 `push2his.eastmoney.com` | 实时 | — |
| 公告 | 东方财富 `np-anotice-stock.eastmoney.com` | 实时 | — |
| 龙虎榜/席位 | 东方财富 `datacenter-web.eastmoney.com` | **T+1** | 当日数据次日凌晨上线 |
| 板块/机构调研 | 东方财富 `datacenter-web.eastmoney.com` | 实时 | — |
| 融资融券 | 东方财富 `datacenter-web.eastmoney.com` | — | ⚠️ 报表名已于2026.7下线 |

## 架构

```
server.py  (1198 行纯 Python)
├── 新浪 API 封装  → 实时行情/指数/ETF
├── 东方财富 API 封装 → K线/公告/板块/龙虎榜/北向资金
├── MCP JSON-RPC 框架（手写，不依赖 mcp SDK）
└── 17 个工具注册 + 路由（含 6 个情绪维度工具）
```

## 依赖

- Python ≥ 3.11
- `requests`（唯一外部依赖）

## 已知问题 & 故障工具

### ❌ 不可用（API 侧）

| 工具 | 问题 | 根因 | 解决思路 |
|------|------|------|---------|
| `margin_trading` (融资融券) | 返回"报表配置不存在" | 东财 datacenter 报表 `RPT_MARGIN_TRADING_DAILY` / `RPT_MUTUAL_MARKET_DAILY` 已于 2026.7 下线 | ① 寻找东财新版融资融券 API；② 改用 push2 KAMT 接口（需确认 secid）；③ 暂时用 `market_breadth` 涨跌停+ETF情绪替代 |
| `guba_hot` (股吧热度) | 返回"无法解析"或空 | 股吧旧接口 `guba.eastmoney.com/interface/GetData.aspx` 已废弃，所有已知端点 404 | ① 抓取东财新版股吧页面 API（需逆向）；② 改用 `financial_news` 关键词搜索替代散户情绪；③ 用 push2 客户端接口（需确认新 URL） |
| `sector_detail` (板块成分股) | 返回空数组 `[]` | ① 东财 datacenter 报表 `RPT_BOARD_COMPONENT` 已下线；② push2 API 在某些网络环境不可达 | ① 找新版板块报表名（如 `RPT_BOARD_LIST` 等变体）；② 用新浪行业接口 `vip.stock.finance.sina.com.cn`；③ 用 push2 `fs=b:BK代码` 参数（需网络可达） |

### ⚠️ 网络不稳定（push2his 代理连接）

| 工具 | 问题 | 根因 | 解决思路 |
|------|------|------|---------|
| `stock_history` (历史K线) | ProxyError: 代理连接断开 | 该工具访问 `push2his.eastmoney.com`（Azure CDN），需走代理（Clash 7890）。但代理连接偶发 RemoteDisconnected | ① Clash 中为 `push2his.eastmoney.com` 配置独立代理节点；② 或找替代 K 线数据源（如新浪 `finance.sina.com.cn` 历史接口）；③ 增加重试+超时 |
| `etf_history` (ETF历史净值) | 同上 | 同走 `push2his` | 同上 |
| `quick_analysis` (30日走势) | 实时行情可用，历史走势报错 | 实时行情走新浪（OK），30日走势走 `push2his`（挂） | 实时部分正常使用；历史走势参考 `stock_history` 的解决方案 |

> **现状**：17 个工具中 **11 个正常**、3 个 API 侧故障、3 个网络层不稳定。核心数据（大盘/个股/ETF实时/龙虎榜/情绪/公告/新闻）全部可用。

### 已修复的问题（2026-07-23）

- **龙虎榜 T+1 延迟**：当日数据次日凌晨上线，已内置自动回退（最多回溯5天）
- **公告查询漏报**：`stock_announcements` 改用 `stock_list` 精准过滤，解决大票公告遗漏
- **财经新闻占位**：`financial_news` 从空壳改为新浪财经 API 实现

## 扩展：邮件报告 + 定时任务

`examples/email-reports/` 目录包含完整的日报/周报自动化方案：

- `send_email.py` — Markdown → PDF 附件邮件发送
- `email_config.example.json` — 多邮箱配置模板（支持 163/QQ/Gmail）
- `.md-to-pdf.json` — A4 PDF 样式
- `README.md` — 从安装到定时集成的完整指南

配合 Claude Code cron 可实现：盘前速览(8:30)、盘后复盘(15:33)、宏观周报(周六)、行业周报(周日) 全自动生成。

## 自定义

### 添加关注的 ETF

编辑 `server.py` 的 `POPULAR_ETFS` 列表：

```python
POPULAR_ETFS = [
    ("sh510300", "沪深300ETF"),
    ("你的代码", "你的ETF名称"),
]
```

### 添加关注的板块

编辑 `CONCEPT_BOARDS` 字典：

```python
CONCEPT_BOARDS = {
    "你的板块名": "东方财富板块代码",
}
```

板块代码可以在东方财富概念板块页面 URL 中找到。

## 相关项目

- [东方财富](https://www.eastmoney.com/) — 数据来源
- [新浪财经](https://finance.sina.com.cn/) — 数据来源
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) — 协议规范

## License

MIT