Metadata-Version: 2.4
Name: akshare-stock-mcp
Version: 0.1.0
Summary: MCP Server for akshare stock data - A股股票数据MCP服务
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: akshare>=1.14.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pandas>=2.0.0
Description-Content-Type: text/markdown

# akshare-stock-mcp 📈

> 基于 MCP (Model Context Protocol) 标准协议的 A 股股票数据服务

<div align="center">

  <h3>让任何 AI Agent 读懂 A 股</h3>
  <p>Claude Desktop / OpenClaw / Hermes / Cursor / 任何MCP客户端 · 20个专业工具 · 智能缓存 · 标准协议</p>

  <p>
    <img src="https://img.shields.io/badge/Protocol-MCP_1.0-blue?style=flat-square" alt="MCP">
    <img src="https://img.shields.io/badge/Python-3.10+-3776ab?style=flat-square" alt="Python">
    <img src="https://img.shields.io/badge/Data-Akshare-orange?style=flat-square" alt="Akshare">
    <img src="https://img.shields.io/badge/Transport-stdio%20%7C%20SSE%20%7C%20HTTP-brightgreen?style=flat-square" alt="Transport">
    <img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="License">
  </p>

</div>

---

**akshare-stock-mcp** 是连接 AI 与 [akshare](https://github.com/akfamily/akshare) 金融数据的桥梁。它实现了 Model Context Protocol (MCP) 标准协议，让任何支持 MCP 的 AI 客户端能够直接调用 **20 个**专业股票数据接口——实时行情、历史K线、财务报表、北向资金、龙虎榜等。

**零 API Key**：akshare 是免费开源库，无需注册、无需 Token，装上就能用。

---

## 🚀 快速开始（3步，60秒）

### 第 1 步：安装

```bash
git clone <repository-url> akshare-mcp-server
cd akshare-mcp-server

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -e .
```

### 第 2 步：验证

```bash
# 测试 Server 能否启动
python -m akshare_stock_mcp.server --help
```

输出应显示：
```
usage: server [-h] [--transport {stdio,sse,streamable-http}] [--host HOST] [--port PORT]
```

### 第 3 步：连接你的 AI 客户端

选择你使用的客户端，复制对应的配置 ↓

---

## 🔌 客户端接入指南

### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "akshare-stock": {
      "command": "/你的路径/akshare-mcp-server/.venv/bin/python",
      "args": ["-m", "akshare_stock_mcp.server"],
      "cwd": "/你的路径/akshare-mcp-server/src"
    }
  }
}
```

重启 Claude Desktop，输入 "帮我查一下贵州茅台的实时行情" 测试。

---

### OpenClaw

编辑 `~/.openclaw/openclaw.json`：

```json
{
  "mcpServers": {
    "akshare-stock": {
      "command": "/你的路径/akshare-mcp-server/.venv/bin/python",
      "args": ["-m", "akshare_stock_mcp.server"],
      "cwd": "/你的路径/akshare-mcp-server/src",
      "transport": "stdio"
    }
  }
}
```

然后重启网关：
```bash
openclaw gateway restart
openclaw mcp list   # 验证：应显示 akshare-stock running 20 tools
```

---

### Hermes Agent

编辑 `~/.hermes/config.yaml`：

```yaml
mcp_servers:
  akshare-stock:
    command: "/你的路径/akshare-mcp-server/.venv/bin/python"
    args: ["-m", "akshare_stock_mcp.server"]
    cwd: "/你的路径/akshare-mcp-server/src"
    timeout: 120
```

或用 CLI 一键添加：
```bash
hermes mcp add --command /你的路径/.venv/bin/python --args "-m,akshare_stock_mcp.server"
```

---

### Cursor

1. 打开 Cursor → Settings → Features → MCP
2. 点击 "+ Add New MCP Server"
3. 填写：
   - **Name**: `akshare-stock`
   - **Type**: `stdio`
   - **Command**: `/你的路径/akshare-mcp-server/.venv/bin/python -m akshare_stock_mcp.server`

---

### 任何支持 MCP 的客户端（通用）

本服务遵循 MCP 1.0 标准协议，理论上兼容所有 MCP 客户端。

**Stdio 模式**（本地子进程）：
```bash
/你的路径/.venv/bin/python -m akshare_stock_mcp.server
```

**HTTP 模式**（远程/共享）：
```bash
# 启动 HTTP 服务
source .venv/bin/activate
PYTHONPATH=src python -m akshare_stock_mcp.server --transport streamable-http --port 8765

# 客户端连接地址
# Streamable HTTP: http://localhost:8765/mcp
# SSE:             http://localhost:8765/sse
```

在客户端中添加 MCP Server，URL 填 `http://localhost:8765/mcp` 即可。

---

## 🧰 工具列表（20个）

### 📊 实时行情
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_stock_realtime` | 单只股票实时行情 | `symbol`: 股票代码 |
| `get_market_realtime_top` | 涨幅/成交额/换手率排行 | `top_n`: 数量, `sort_by`: 排序字段 |

### 📈 历史K线
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_stock_history` | 日/周/月线（支持复权） | `symbol`, `period`, `start_date`, `end_date`, `adjust` |
| `get_stock_history_min` | 1/5/15/30/60分钟线 | `symbol`, `period`, `start_date`, `end_date` |

### 🏢 个股信息
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_stock_info` | 上市日期、行业、股本等 | `symbol` |
| `search_stock` | 按名称/代码模糊搜索 | `keyword` |

### 💰 财务数据
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_stock_financial_abstract` | 营收、净利润、ROE等核心指标 | `symbol` |
| `get_stock_financial_report` | 利润表/资产负债表/现金流量表 | `symbol`, `report_type` |
| `get_stock_shareholders` | 十大股东 | `symbol` |
| `get_stock_dividend` | 历史分红送转记录 | `symbol` |

### 📉 市场统计
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_market_pe_pb` | A股整体PE/PB估值水平 | 无 |
| `get_sector_performance` | 行业板块涨跌排行 | 无 |
| `get_sector_stocks` | 指定行业成分股 | `sector_name` |
| `get_limit_up_down` | 涨跌停统计 | `date`（可选） |

### 🌊 北向资金
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_northbound_flow` | 沪深港通净流入 | 无 |
| `get_northbound_top_stocks` | 外资重仓股排行 | `market` |

### 🐉 龙虎榜 & 融资融券
| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_dragon_tiger` | 机构/游资买卖明细 | `date`（可选） |
| `get_margin_data` | 市场杠杆水平 | 无 |

### 🛠 管理
| 工具名 | 说明 |
|--------|------|
| `clear_cache` | 清空所有缓存 |
| `get_cache_status` | 查看缓存状态 |

---

## 💡 使用示例

连接成功后，你可以直接用自然语言问 AI：

```
"帮我查一下贵州茅台最近一个月的K线数据"
"A股今天涨幅前10的股票有哪些？"
"北向资金最近流入了哪些股票？"
"平安银行的财务摘要，营收和净利润趋势如何？"
"半导体行业板块有哪些龙头股？"
"今天的龙虎榜数据"
```

---

## 🏗 架构

```
┌─────────────────────────────────────────────────┐
│  AI Client (Claude / OpenClaw / Hermes / Cursor) │
│                        │                         │
│              MCP Protocol (JSON-RPC 2.0)         │
│              stdio / SSE / Streamable HTTP        │
│                        ↓                         │
│           ┌─────────────────────────┐            │
│           │  akshare-stock-mcp      │            │
│           │  ┌───────────────────┐  │            │
│           │  │   智能缓存层       │  │            │
│           │  │  (30s~24h 分级)    │  │            │
│           │  └───────┬───────────┘  │            │
│           │          ↓              │            │
│           │  ┌───────────────────┐  │            │
│           │  │   20个工具        │  │            │
│           │  │  行情/K线/财务...  │  │            │
│           │  └───────┬───────────┘  │            │
│           └──────────┼──────────────┘            │
│                      ↓                           │
│              ┌───────────────┐                   │
│              │  akshare 库   │                   │
│              └───────┬───────┘                   │
│                      ↓                           │
│         东方财富 / 新浪 / 腾讯 等数据源            │
└─────────────────────────────────────────────────┘
```

---

## ⚡ 与同类项目的区别

| 特性 | 本项目 | 其他 akshare MCP |
|------|--------|-----------------|
| 工具数量 | 20个精选 | 1000+ 自动生成（选择困难） |
| 缓存 | 智能分级缓存 | 无缓存（易被限流） |
| 输出格式 | 统一JSON schema | 原始DataFrame字符串 |
| 错误处理 | 友好错误信息 | 原始异常堆栈 |
| 传输协议 | stdio + SSE + HTTP | 仅stdio |
| 股票代码 | 兼容多种格式 | 仅纯数字 |

---

## 📄 许可证

MIT License

---

## 🙏 致谢

- [akshare](https://github.com/akfamily/akshare) — 数据源
- [MCP](https://modelcontextprotocol.io) — 协议标准
- [Anthropic](https://www.anthropic.com) — MCP 协议设计
