Metadata-Version: 2.4
Name: agushuju-mcp
Version: 0.1.0
Summary: 爱股数据（agushuju.com）MCP Server — 在 Claude Desktop / Cursor 等 AI 客户端查询 A 股/基金/期货数据
Author: agushuju
License: MIT
Keywords: mcp,agushuju,stock,futures,finance,quant
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=2.2
Requires-Dist: agushuju>=0.1.0

# agushuju-mcp — 爱股数据 MCP Server

在 Claude Desktop、Cursor 等 MCP 客户端里用自然语言查 A 股/基金/期货数据：

> "平安银行最近的日线行情" · "今天涨停的股票有哪些" · "螺纹钢主力合约这个月的走势"

底层封装[爱股数据](https://www.agushuju.com) REST API（复用 [agushuju Python SDK](../python)），
使用你自己的平台 token——**鉴权、限流、计费全部走平台既有体系**，与本 Server 无关。

## 工具清单（首批 12 + 1）

| 工具 | 数据 |
|------|------|
| `stock_basic` | 股票基础信息（名称/行业/上市日期） |
| `stock_daily` | A 股日线行情 |
| `stock_daily_basic` | 每日指标（换手率/量比/市盈率/市值） |
| `trade_calendar` | 交易日历（SSE/SZSE） |
| `stock_moneyflow` | 个股资金流向（主力/大中小单） |
| `stock_top_list` | 龙虎榜每日明细 |
| `index_daily` | 指数日线 |
| `fund_daily` | ETF/基金日线 |
| `futures_daily` | 期货日线 |
| `stock_fina_indicator` | 财务指标（EPS/ROE/营收增速） |
| `stock_limit_list` | 每日涨跌停列表 |
| `stock_stk_limit` | 每日涨跌停价格 |
| `health_check` | 服务状态探活 |

**参数约定**：日期一律 `YYYY-MM-DD`；代码带交易所后缀（股票 `000001.SZ`、指数 `000001.SH`、期货 `RB2601.SHF`）；返回 markdown 表格，默认 10 行、单次最多 50 行，`offset` 翻页。

## 安装与配置

### 1. 获取 token

在 [API Key 管理页](https://www.agushuju.com/userapikey) 创建你的 token。

### 2. 安装

```bash
# agushuju SDK 尚未发布 PyPI，先从本仓库安装（发版后此步可省略）
pip install -e sdk/python
pip install -e sdk/mcp
```

### 3. Claude Desktop 配置

`claude_desktop_config.json`（Claude Desktop → 设置 → Developer → Edit Config）：

```json
{
  "mcpServers": {
    "agushuju": {
      "command": "agushuju-mcp",
      "env": {
        "AGUSHUJU_TOKEN": "你的token"
      }
    }
  }
}
```

Windows 下 `command` 可能需要写 python 可执行文件完整路径，用
`python -c "import sys; print(sys.executable)"` 查出后配置为：

```json
{
  "mcpServers": {
    "agushuju": {
      "command": "C:\\Users\\你\\...\\python.exe",
      "args": ["-m", "agushuju_mcp.server"],
      "env": { "AGUSHUJU_TOKEN": "你的token" }
    }
  }
}
```

### 4. Cursor 配置

`.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "agushuju": {
      "command": "agushuju-mcp",
      "env": { "AGUSHUJU_TOKEN": "你的token" }
    }
  }
}
```

配置后重启客户端，工具列表出现「爱股数据」即接入成功；先问一句
"查一下服务状态" 跑 `health_check` 验证链路。

## 环境变量

| 变量 | 说明 |
|------|------|
| `AGUSHUJU_TOKEN` | 平台 API Key（必填） |
| `AGUSHUJU_API_BASE` | 服务地址，默认 https://www.agushuju.com（本地调试可指 http://127.0.0.1:8181） |

## 错误排查

| 现象 | 处理 |
|------|------|
| 未设置 AGUSHUJU_TOKEN | 检查 mcpServers 配置的 env 字段 |
| code=401 | token 无效/过期，到 [API Key 页](https://www.agushuju.com/userapikey)重建 |
| code=429 | 触发限流（免费档每接口 200 次/日），见 [定价页](https://www.agushuju.com/pricing) |
| 服务不可达 | 用 `health_check` 探活；查看 [服务状态页](https://www.agushuju.com/status) |

## 相关链接

- 接口文档：https://www.agushuju.com/doc
- 定价与限流：https://www.agushuju.com/pricing
- Python SDK：[sdk/python](../python)
