# Ashare MCP Server

A股/港股/美股股票行情数据 MCP Server，基于 [Ashare](https://github.com/mpquant/Ashare) 封装，支持搜索、K线、实时行情、多股票对比、K线图生成。

## 功能概览

| 工具 | 功能 | 市场 |
|------|------|------|
| `ashare_search` | 按名称/代码搜索股票 | A股+港股+美股 |
| `ashare_get_quote` | 获取K线行情数据 | A股+港股+美股 |
| `ashare_batch_quote` | 批量获取行情摘要 | A股+港股+美股 |
| `ashare_get_realtime` | 获取实时价格 | A股+港股+美股 |
| `ashare_compare` | 多股票行情对比 | A股+港股+美股 |

## 安装

```bash
cd ashare_mcp
pip install -r requirements.txt
```

依赖：`mcp`, `pandas`, `requests`, `pydantic`, `matplotlib`, `mplfinance`, `akshare`

## 启动

```bash
python server.py
```

服务通过标准输入输出（stdio）通信，等待 MCP 客户端连接。

## 工具详细说明

### 1. ashare_search - 搜索股票

按名称或代码模糊搜索，返回匹配的股票列表。

**参数：**
- `keyword` (string, 必填): 搜索关键词，可以是股票名称或代码

**示例调用：**
```
ashare_search(keyword="茅台")
ashare_search(keyword="腾讯")
ashare_search(keyword="00700")
ashare_search(keyword="apple")
```

**返回格式：**
```markdown
### 搜索结果: '腾讯'

| 名称 | 代码 | 市场 |
|------|------|------|
| 腾讯控股 | hk00700 (hk00700) | 香港 |
| 腾讯音乐-SW | hk01698 (hk01698) | 香港 |
| 腾讯音乐 | TME (TME) | 美股 |

共找到 3 条结果
```

**数据来源：** 新浪财经（A股）+ 东方财富（港股/美股），自动合并去重。

---

### 2. ashare_get_quote - 获取K线行情

获取单只股票的K线数据，支持多种周期，可同时生成K线图。

**参数（JSON）：**
- `code` (string, 必填): 证券代码
- `frequency` (string, 可选): K线周期，默认 `1d`
- `count` (int, 可选): K线数量，默认 `10`，最大 `500`
- `end_date` (string, 可选): 结束日期，格式 `YYYY-MM-DD`
- `chart` (bool, 可选): 是否生成K线图，默认 `true`

**示例调用：**
```
ashare_get_quote(params={"code": "sh600519", "frequency": "1d", "count": 10})
ashare_get_quote(params={"code": "hk00700", "frequency": "60m", "count": 20, "chart": false})
ashare_get_quote(params={"code": "sz002594", "frequency": "1w", "count": 5})
```

**返回格式：**
```markdown
### sh600519 (日线)

| 时间 | 开盘 | 收盘 | 最高 | 最低 | 成交量 |
|------|------|------|------|------|--------|
| 2026-07-01 | 1500.00 | 1520.00 | 1530.00 | 1490.00 | 12,345,678 |
| 2026-07-02 | 1520.00 | 1510.00 | 1525.00 | 1500.00 | 10,234,567 |

**最新价**: 1510.00 | **最高**: 1530.00 | **最低**: 1490.00

---

### sh600519 K线图

![K线图](https://iili.io/xxxxx.png)

**图片链接**: https://iili.io/xxxxx.png
```

**图表特性（当chart=true时）：**
- 深色主题（#1a1a2e 背景）
- K线 + 涨跌颜色（红涨绿跌）
- MA5（橙色）+ MA10（紫色）均线
- 成交量柱状图
- 自动上传到图床
- 分辨率 150 DPI

---

### 3. ashare_batch_quote - 批量行情摘要

同时获取多只股票的最新价格和涨跌幅。

**参数（JSON）：**
- `codes` (string, 必填): 逗号分隔的证券代码
- `frequency` (string, 可选): K线周期，默认 `1d`
- `count` (int, 可选): 每只股票获取的K线数量，默认 `5`

**示例调用：**
```
ashare_batch_quote(params={"codes": "sh600519,sz002594,hk00700"})
```

**返回格式：**
```markdown
### 批量行情摘要 (日线)

| 代码 | 最新价 | 涨跌额 | 涨跌幅 |
|------|--------|--------|--------|
| sh600519 | 1510.00 | +10.00 | +0.67% ↑ |
| sz002594 | 320.50 | -5.20 | -1.60% ↓ |
| hk00700 | 460.20 | -9.40 | -2.00% ↓ |
```

---

### 4. ashare_get_realtime - 实时行情

快速获取单只股票的当前价格。

**参数：**
- `code` (string, 必填): 证券代码

**示例调用：**
```
ashare_get_realtime(code="sh600519")
ashare_get_realtime(code="hk00700")
```

**返回格式（A股）：**
```markdown
### sh600519 实时行情

- **日期**: 2026-07-10
- **最新价**: 1510.00
- **开盘价**: 1500.00
- **最高价**: 1530.00
- **最低价**: 1490.00
- **成交量**: 12,345,678
```

**返回格式（港股）：**
```markdown
### hk00700 实时行情

- **名称**: 腾讯控股
- **最新价**: 460.20
- **开盘价**: 472.80
- **最高价**: 473.60
- **最低价**: 458.80
- **成交量**: 40,440,298
```

---

### 5. ashare_compare - 多股票对比

同时获取多只股票的K线数据，方便对比分析。

**参数：**
- `codes` (string, 必填): 逗号分隔的证券代码
- `count` (int, 可选): 每只股票获取的K线数量，默认 `5`

**示例调用：**
```
ashare_compare(codes="sh600519,sz002594,hk00700", count=5)
```

**返回格式：**
```markdown
### sh600519 (日线)

| 时间 | 开盘 | 收盘 | 最高 | 最低 | 成交量 |
|------|------|------|------|------|--------|
| ... | ... | ... | ... | ... | ... |

---

### sz002594 (日线)

| 时间 | 开盘 | 收盘 | 最高 | 最低 | 成交量 |
|------|------|------|------|------|--------|
| ... | ... | ... | ... | ... | ... |
```

最多同时对比 10 只股票。

---

## 证券代码格式

### A股

| 格式 | 示例 | 说明 |
|------|------|------|
| 通达信 | `sh600519`, `sz002594` | sh=上海, sz=深圳 |
| 聚宽 | `600519.XSHG`, `002594.XSHE` | XSHG=上海, XSHE=深圳 |
| 纯数字 | `600519` | 自动判断市场 |

### 港股

| 格式 | 示例 | 说明 |
|------|------|------|
| hk前缀 | `hk00700` | 推荐格式 |
| 5位数字 | `00700` | 自动识别为港股 |

### 美股

| 格式 | 示例 | 说明 |
|------|------|------|
| 股票代码 | `AAPL`, `TME` | 直接使用代码 |

## K线周期

| 参数 | 说明 | 最小间隔 |
|------|------|----------|
| `1m` | 1分钟线 | 实时 |
| `5m` | 5分钟线 | 实时 |
| `15m` | 15分钟线 | 实时 |
| `30m` | 30分钟线 | 实时 |
| `60m` | 60分钟线 | 实时 |
| `1d` | 日线 | 每交易日 |
| `1w` | 周线 | 每交易周 |
| `1M` | 月线 | 每交易月 |

## 数据来源

| 市场 | K线数据 | 实时行情 | 搜索 |
|------|---------|----------|------|
| A股 | 新浪财经（主）/ 腾讯股票（备） | 新浪财经 | 新浪财经 |
| 港股 | 腾讯股票 | 腾讯股票 | 东方财富 |
| 美股 | AkShare | AkShare | 东方财富 |

图床：freeimage.host（免费，无需API Key）

## MCP 配置

### MiMoCode / Claude Desktop

在 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "ashare": {
      "command": "python",
      "args": ["D:/code/stock/ashare_mcp/server.py"]
    }
  }
}
```

### 其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用，启动命令：

```bash
python D:/code/stock/ashare_mcp/server.py
```

## 文件结构

```
ashare_mcp/
├── server.py          # MCP Server 主文件（5个工具）
├── Ashare.py          # Ashare 行情库（A股数据源）
├── requirements.txt   # Python 依赖
├── start.bat          # Windows 启动脚本（自动安装依赖）
├── README.md          # 本文档
└── .gitignore         # Git 忽略规则
```

## 开发说明

### 依赖自动安装

server.py 包含自动依赖安装逻辑，启动时会检查并安装缺失的依赖包。

### 数据源

- **A股**: 使用 Ashare 库（基于新浪财经）
- **港股**: 使用东方财富 API + 腾讯股票 API
- **美股**: 使用 AkShare 库
- **搜索**: 使用新浪财经（A股）+ 东方财富（港股/美股）

### 图表生成

使用 matplotlib + mplfinance 生成专业K线图，支持：
- 深色主题
- 涨跌颜色（红涨绿跌）
- 均线（MA5、MA10）
- 成交量柱状图
- 自动上传到图床