内容
# ashare-mcp
基于 [baostock](http://baostock.com) 构建的MCP服务器，暴露了 **全部 23 个** baostock 数据接口作为MCP工具：K线、季度财务数据（利润 / 营运 / 增长 / 资产负债 / 现金流 / 杜邦分析）、业绩快报和预测报告、分红数据、调整因子、行业分类、指数成分股、交易日历和宏观经济数据系列。
此外，它还提供了两个 **公告（披露）工具**，基于 EastMoney 的公开 HTTP API —— 列出股票公告和下载 PDF 文件，因为 baostock 没有公告接口。EastMoney 的接口在大陆以外地区可访问，因此即使 baostock 的数据端口被封锁，这些工具仍可正常使用。
数据层位于 `DataProvider` 抽象层之后。v1 版本提供了 `baostock` 后端，并预留了接口以便后续添加其他数据源，而无需修改工具层。公告工具与数据源并存（它们根本不经过 baostock）。
## 安装
```bash
uv sync
```
## 运行（stdio）
```bash
uv run ashare-mcp
```
在 stdio MCP 客户端（Claude Desktop / Claude Code / Cursor）中配置：
```json
{
"mcpServers": {
"ashare": {
"command": "uv",
"args": ["--directory", "/path/to/ashare-mcp", "run", "ashare-mcp"]
}
}
}
```
## 工具
| 类别 | 工具 |
| --- | --- |
| 市场 | `get_stock_basic` `get_all_stock` `get_trade_dates` `get_history_k_data` |
| 分红 / 调整 | `get_dividend_data` `get_adjust_factor` |
| 季度财务数据 | `get_profit_data` `get_operation_data` `get_growth_data` `get_balance_data` `get_cash_flow_data` `get_dupont_data` |
| 报告 | `get_performance_express_report` `get_forecast_report` |
| 行业 / 指数成分股 | `get_stock_industry` `get_sz50_stocks` `get_hs300_stocks` `get_zz500_stocks` |
| 宏观经济 | `get_deposit_rate_data` `get_loan_rate_data` `get_required_reserve_ratio_data` `get_money_supply_data_month` `get_money_supply_data_year` |
| 公告（EastMoney） | `get_stock_announcements` `download_stock_announcement` |
| 实用工具 | `get_current_time` |
所有 baostock 支持的数据工具都返回统一的数据格式：
`{"count": int, "fields": [...], "data": [{...}, ...]}`。公告工具返回其自己的数据格式（见下文）。
### 公告（披露）
两个基于 EastMoney 的工具，与 baostock 无关：
- **`get_stock_announcements(code, start_date="", end_date="", page_size=50, keyword="")`**
— 列出股票公告，新最先。
`code` 支持 `sh.600519` / `sz.002049` / `600519` 格式。
`start_date` / `end_date` 为包含的 `YYYY-MM-DD` 日期筛选。
`keyword` 为标题的区分大小写的子字符串（例如 `重组`）。
返回 `{code, count, data:[{art_code, title, notice_date, type, pdf_url_guess}]}`。
- **`download_stock_announcement(art_code, save_dir="")`** — 通过上述返回的 `art_code` 下载公告 PDF 文件。通过 EastMoney 的内容 API 解析实际附件 URL（如果需要，备用 `H2_<art_code>_1.pdf` 惯例）。
返回 `{art_code, title, save_dir, files:[{path, url, bytes}]}` — 使用 MCP 客户端的文件/读取工具打开返回的 `path` 以读取 PDF 文件。
典型流程：调用 `get_stock_announcements` → 选择 `art_code` → `download_stock_announcement` → 读取保存的 PDF 文件。
## 代码
传递 baostock 格式的代码：`sh.600519`、`sz.000001`、`bj.430047`。裸 6 位代码（例如 `600519`）会尽力标准化，但 **模糊指数代码**（例如 `000001` 既是 SSE Composite `sh.000001` 又是平安银行 `sz.000001`）应显式添加前缀。
## 配置
| 环境变量 | 默认值 | 含义 |
| --- | --- | --- |
| `ASHARE_SOURCE` | `baostock` | 数据源。目前 v1 版本仅支持 `baostock`。 |
| `ASHARE_DOWNLOAD_DIR` | `~/.cache/ashare-mcp/announcements` | `download_stock_announcement` 保存 PDF 文件的目录。在 MCP 客户端配置中设置此项以将下载文件指向项目文件夹。工具的显式 `save_dir` 参数始终优先。 |
## 开发
```bash
uv run pytest -q # 单元测试（无网络）
uv run pytest -q -m network # baostock 存活测试
```
## 注意事项
- baostock 的数据端口必须能从您的网络访问（在中国大陆可访问；在其他地区可能会超时）。如果 baostock 工具开始超时，请首先检查这一点。EastMoney 公告工具使用单独的 HTTPS 接口，通常在大陆以外地区可访问。
- baostock 无需注册，但每个进程仍必须调用 `bs.login()` 以打开会话 — 该服务器登录一次，关闭时注销。
- 公告工具仅使用标准库（无新依赖），并在 baostock 会话上运行，因此即使 baostock 关闭，它们仍可继续工作。
