# a-share-mcp

**A股数据 MCP Server** — 让 Claude / 任意 MCP 客户端直接查询 A股行情数据。

A-share data MCP server: K-line (Tencent source, qfq/hfq), limit-up/down pools, per-stock fund flow, index quotes, stock news.

> 数据仅供研究参考,不构成投资建议。For research only, not investment advice.

## 为什么是这个组合

A股数据接口的可用性是个坑:东方财富(push2)系接口间歇性限流断连,很多教程接口实际已死。本服务的选型来自长期实测:

| 工具 | 数据源 | 稳定性 |
|---|---|---|
| `get_kline` K线(日/周/月,前/后复权) | 腾讯 `ifzq.gtimg.cn` | ★ 稳定,主力链路 |
| `get_limit_up_pool` 涨停池(连板数/炸板/行业) | 东财 via akshare | 间歇限流,内置自动重试 |
| `get_limit_down_pool` 跌停池 | 东财 via akshare | 同上 |
| `get_fund_flow` 个股逐日资金流 | 东财 via akshare | 同上 |
| `get_index_spot` 主要指数行情 | 东财 via akshare | 同上 |
| `get_stock_news` 个股新闻 | 东财 via akshare | 同上 |

内置处理:
- 股票代码自动归一(`600519` / `sh600519` / `sz000001` 均可,自动推断市场)
- 东财接口连续失败自动重试,最终报错给出可行动提示而非裸异常
- 绕开 akshare 涨跌停池函数"默认日期写死为 2024 年"的坑(自动回落到当天)

## 快速开始

**方式一:uvx(免安装,推荐)**

```bash
uvx --from git+https://github.com/mazihua-lgtm/a-share-mcp a-share-mcp
```

**方式二:pip**

```bash
pip install git+https://github.com/mazihua-lgtm/a-share-mcp
a-share-mcp   # stdio transport
```

要求 Python >= 3.10。

## 客户端配置

**Claude Desktop / 通用 MCP 客户端** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "a-share": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mazihua-lgtm/a-share-mcp", "a-share-mcp"]
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add a-share -- uvx --from git+https://github.com/mazihua-lgtm/a-share-mcp a-share-mcp
```

## 工具一览

| Tool | 参数 | 说明 |
|---|---|---|
| `get_kline` | `symbol, period=day, count=75, adjust=qfq` | K线,period: day/week/month,adjust: qfq/hfq/none,count ≤ 800 |
| `get_limit_up_pool` | `date?` (YYYYMMDD) | 涨停池:连板数、炸板次数、封板资金、所属行业 |
| `get_limit_down_pool` | `date?` (YYYYMMDD) | 跌停池(仅最近 30 个交易日) |
| `get_fund_flow` | `symbol, days=10` | 主力/超大单/大单/中单/小单逐日净流入 |
| `get_index_spot` | — | 上证/深证/创业板/沪深300 等实时行情 |
| `get_stock_news` | `symbol, limit=20` | 个股新闻:标题/摘要/时间/来源/链接 |

涨跌停池 `date` 缺省为当天:盘中调用返回实时池,盘前为空属正常。

## 本地开发

```bash
git clone https://github.com/mazihua-lgtm/a-share-mcp && cd a-share-mcp

# 数据层冒烟测试(无需 mcp 包,Python 3.9 可跑)
python3 tests/smoke_test.py

# MCP 协议端到端测试(需 Python >= 3.10)
uv venv --python 3.12 .venv && uv pip install -e . && .venv/bin/python tests/mcp_client_test.py
```

## Roadmap

- [ ] 龙虎榜、板块资金流
- [ ] 分钟级 K线
- [ ] 可选 x402 按调用计费(配合 [cashier-mcp](https://github.com/mazihua-lgtm/cashier-mcp))

## License

MIT