# AkShare MCP 服务器

基于 FastMCP 2.0 和 SSE 协议的 AkShare 金融数据 MCP 服务器。

## 功能特性

- 🚀 基于 SSE 协议，零依赖、即开即用
- 📊 集成 AkShare 金融数据接口
- 📋 Markdown 表格格式输出，美观易读
- 🔧 支持环境变量配置
- 📝 完整的日志记录
- 🛡️ 参数验证和错误处理

## 已实现的工具

### stock_us_hist - 美股历史行情数据

获取美股历史行情数据，支持不同周期和复权方式。

**参数：**
- `symbol`: 美股代码，例如 '106.TTE' 或 'AAPL'
- `period`: 数据周期，选择 {'daily', 'weekly', 'monthly'}，默认 'daily'
- `start_date`: 开始日期，格式 YYYYMMDD，默认 '20210101'
- `end_date`: 结束日期，格式 YYYYMMDD，默认 '20240214'
- `adjust`: 复权类型，''=未复权, 'qfq'=前复权, 'hfq'=后复权，默认 ''

**返回数据：**
- 日期、开盘、收盘、最高、最低价格（美元）
- 成交量（股）、成交额（美元）
- 振幅、涨跌幅、涨跌额、换手率

### stock_hk_hist - 港股历史行情数据

获取港股历史行情数据，支持不同周期和复权方式。

**参数：**
- `symbol`: 港股代码，例如 '00593' 或 '08367'
- `period`: 数据周期，选择 {'daily', 'weekly', 'monthly'}，默认 'daily'
- `start_date`: 开始日期，格式 YYYYMMDD，默认 '19700101'
- `end_date`: 结束日期，格式 YYYYMMDD，默认 '22220101'
- `adjust`: 复权类型，''=未复权, 'qfq'=前复权, 'hfq'=后复权，默认 ''

**返回数据：**
- 日期、开盘、收盘、最高、最低价格（港元）
- 成交量（股）、成交额（港元）
- 振幅、涨跌幅、涨跌额、换手率

### stock_zh_a_hist - A股历史行情数据

获取沪深京A股历史行情数据，支持不同周期和复权方式。

**参数：**
- `symbol`: A股代码，例如 '000001'(平安银行) 或 '603777'
- `period`: 数据周期，选择 {'daily', 'weekly', 'monthly'}，默认 'daily'
- `start_date`: 开始日期，格式 YYYYMMDD，默认 '20210301'
- `end_date`: 结束日期，格式 YYYYMMDD，默认 '20240528'
- `adjust`: 复权类型，''=不复权, 'qfq'=前复权, 'hfq'=后复权，默认 ''

**返回数据：**
- 日期、股票代码、开盘、收盘、最高、最低价格（人民币）
- 成交量（手，1手=100股）、成交额（元）
- 振幅、涨跌幅、涨跌额、换手率

**复权说明：**
- 前复权：保持当前价格不变，调整历史价格，适合技术分析
- 后复权：保证历史价格不变，调整当前价格，适合量化研究

## 输出格式示例

所有工具都返回格式化的 Markdown 表格，包含以下信息：

### 美股/港股输出格式
```markdown
# 美股历史行情数据

**股票代码**: AAPL  
**数据周期**: daily  
**日期范围**: 20240101 ~ 20240214  
**复权方式**: 前复权  
**数据条数**: 32 条  
**货币单位**: 美元 (USD)

| 日期       | 开盘   | 收盘   | 最高   | 最低   | 成交量    | 成交额      | 振幅  | 涨跌幅 | 涨跌额 | 换手率 |
|------------|--------|--------|--------|--------|-----------|-------------|-------|--------|--------|--------|
| 2024-01-02 | 187.15 | 185.64 | 187.90 | 182.73 | 52230000  | 9687420000  | 2.76  | -2.94  | -5.61  | 0.84   |
| 2024-01-03 | 184.22 | 184.25 | 185.88 | 183.43 | 47317000  | 8732510000  | 1.32  | -0.75  | -1.39  | 0.76   |

*数据来源：东方财富网*
```

### A股输出格式
```markdown
# A股历史行情数据

**股票代码**: 000001  
**数据周期**: daily  
**日期范围**: 20240101 ~ 20240528  
**复权方式**: 前复权  
**数据条数**: 95 条  
**货币单位**: 人民币 (CNY)  
**成交量单位**: 手 (1手=100股)

| 日期       | 股票代码 | 开盘  | 收盘  | 最高  | 最低  | 成交量  | 成交额       | 振幅  | 涨跌幅 | 涨跌额 | 换手率 |
|------------|----------|-------|-------|-------|-------|---------|-------------|-------|--------|--------|--------|
| 2024-01-02 | 000001   | 11.88 | 11.78 | 11.96 | 11.72 | 1052468 | 1241250000  | 2.03  | -0.84  | -0.10  | 0.38   |
| 2024-01-03 | 000001   | 11.74 | 11.65 | 11.80 | 11.58 | 892456  | 1042180000  | 1.87  | -1.10  | -0.13  | 0.32   |

*数据来源：东方财富网*  
*注：成交量单位为手，成交额单位为元*
```

## 安装依赖

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

## 启动服务器

### 方法一：直接运行主文件
```bash
python akshare_mcp_server.py
```

### 方法二：使用启动脚本
```bash
python start_server.py
```

## 环境变量配置

可以通过环境变量自定义服务器配置：

```bash
export HOST=127.0.0.1
export PORT=8005
export TRANSPORT=sse
```

## 客户端连接配置

在您的 MCP 客户端中添加以下配置：

```json
{
  "mcpServers": {
    "akshare-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8005/sse",
      "timeout": 60,
      "description": "AkShare金融数据MCP服务器"
    }
  }
}
```

## 使用示例

启动服务器后，您可以通过 MCP 客户端调用各种工具：

### 美股数据示例
```
获取苹果公司(AAPL)近期股价数据：
- symbol: "AAPL"
- period: "daily"
- start_date: "20240101"
- end_date: "20240214"
- adjust: "qfq"
```

### 港股数据示例
```
获取腾讯控股(00700)港股数据：
- symbol: "00700"
- period: "daily"
- start_date: "20240101"
- end_date: "20240214"
- adjust: "qfq"
```

### A股数据示例
```
获取平安银行(000001)A股数据：
- symbol: "000001"
- period: "daily"
- start_date: "20240101"
- end_date: "20240528"
- adjust: "qfq"
```

## 日志

服务器日志会保存在 `logs/akshare_mcp.log` 文件中，包含详细的操作记录和错误信息。

## 项目结构

```
Ptrader-MCP/
├── akshare_mcp_server.py    # 主服务器文件
├── start_server.py          # 启动脚本
├── config.json              # 客户端连接配置
├── requirements.txt         # 依赖文件
├── README.md               # 使用说明
└── logs/                   # 日志目录
```

## 注意事项

1. 确保网络连接正常，AkShare 需要访问外部数据源
2. 某些接口可能有访问频率限制，请适当控制调用频率
3. 数据仅供参考，投资决策请谨慎

## 许可证

本项目基于 MIT 许可证开源。