Metadata-Version: 2.4
Name: iflow-mcp-buuzzy-tushare_mcp
Version: 0.1.2
Summary: A股数据查询服务，基于 MCP (Model Context Protocol) 协议，支持通过 AI 助手用自然语言查询股票数据
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: anyio>=4.9.0
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: bs4>=0.0.2
Requires-Dist: certifi>=2025.4.26
Requires-Dist: charset-normalizer>=3.4.2
Requires-Dist: click>=8.1.8
Requires-Dist: fastapi>=0.115.12
Requires-Dist: h11>=0.16.0
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httptools>=0.6.4
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: idna>=3.10
Requires-Dist: lxml>=5.4.0
Requires-Dist: mcp>=1.7.1
Requires-Dist: numpy>=2.2.5
Requires-Dist: pandas>=2.2.3
Requires-Dist: pydantic-core>=2.33.2
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: pydantic>=2.11.4
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: pytz>=2025.2
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.3
Requires-Dist: simplejson>=3.20.1
Requires-Dist: six>=1.17.0
Requires-Dist: sniffio>=1.3.1
Requires-Dist: soupsieve>=2.7
Requires-Dist: sse-starlette>=2.3.4
Requires-Dist: starlette>=0.46.2
Requires-Dist: tinyshare
Requires-Dist: tqdm>=4.67.1
Requires-Dist: tushare>=1.4.21
Requires-Dist: typing-extensions>=4.13.2
Requires-Dist: typing-inspection>=0.4.0
Requires-Dist: tzdata>=2025.2
Requires-Dist: urllib3>=2.4.0
Requires-Dist: uvicorn>=0.34.2
Requires-Dist: uvloop>=0.21.0
Requires-Dist: watchfiles>=1.0.5
Requires-Dist: websocket-client>=1.8.0
Requires-Dist: websockets>=15.0.1
Description-Content-Type: text/markdown

# Tushare MCP

A股数据查询服务，基于 MCP (Model Context Protocol) 协议，支持通过 AI 助手（Claude Desktop、Cursor 等）用自然语言查询股票数据。

## 重要说明

**本项目使用 `tinyshare` SDK，而非官方 `tushare`。**

如果你想用官方 tushare，修改 `server.py` 第 5 行：
```python
# 当前
import tinyshare as ts

# 改为
import tushare as ts
```

同时修改 `requirements.txt`：将 `tinyshare` 替换为 `tushare==版本号`

## 功能

提供 25 个 MCP 工具，覆盖：
- A股、港股基本信息
- 日线行情、财务报表
- 股东信息、指数数据
- 龙虎榜、交易日历

## 快速开始

### 安装

```bash
# 1. 克隆项目
git clone <你的仓库地址>
cd tushare-mcp

# 2. 创建虚拟环境（macOS 必需）
python3 -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt
```

### 配置 Token

启动后，在 AI 助手中调用 `setup_tushare_token` 工具配置。

或手动创建配置文件：
```bash
mkdir -p ~/.tushare_mcp
echo "TUSHARE_TOKEN=你的token" > ~/.tushare_mcp/.env
```

### 启动服务

```bash
python server.py
```

服务运行在 `http://localhost:8000`

- 健康检查: `http://localhost:8000/`
- API 文档: `http://localhost:8000/docs`
- MCP 端点: `http://localhost:8000/sse`

## 使用

### Claude Desktop

编辑配置文件 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "tushare": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

重启 Claude Desktop 即可使用。

### Cursor

设置 → MCP Servers → 添加：
- 名称: `tushare`
- URL: `http://localhost:8000/sse`

### HTTP API

```bash
# 配置 Token
curl -X POST http://localhost:8000/tools/setup_tushare_token \
  -H "Content-Type: application/json" \
  -d '{"token": "你的token"}'
```

## 工具列表

### Token 管理
- `setup_tushare_token` - 配置 Token
- `check_token_status` - 检查 Token 状态

### 股票信息
- `get_stock_basic_info` - A股基本信息
- `get_hk_stock_basic` - 港股基本信息
- `search_stocks` - 搜索股票

### 行情数据
- `get_daily_prices` - 日线行情（开高低收）
- `get_daily_metrics` - 换手率、PE/PB
- `get_daily_basic_info` - 股本、市值
- `get_period_price_change` - 区间涨跌幅

### 财务数据
- `get_financial_indicator` - 财务指标
- `get_income_statement` - 利润表
- `get_balance_sheet` - 资产负债表
- `get_cash_flow` - 现金流量表
- `get_fina_mainbz` - 主营业务构成

### 股东信息
- `get_shareholder_count` - 股东户数
- `get_top_holders` - 前十大股东

### 指数数据
- `search_index` - 搜索指数
- `get_index_list` - 指数列表
- `get_index_constituents` - 指数成分股
- `get_global_index_quotes` - 国际指数行情

### 特色数据
- `get_pledge_detail` - 股权质押
- `get_top_list_detail` - 龙虎榜
- `get_top_institution_detail` - 龙虎榜机构席位

### 工具
- `get_trade_calendar` - 交易日历
- `get_start_date_for_n_days` - 计算往前N个交易日

## 数据格式

**日期**: `YYYYMMDD`（如 `20240930`）

**股票代码**:
- A股: `000001.SZ` (深圳) / `600000.SH` (上海)
- 港股: `00700.HK`
- 指数: `000300.SH`

**金额单位**:
- 财务数据: 亿元
- 股本: 万股
- 市值: 万元

## Docker 部署

```bash
docker build -t tushare-mcp .
docker run -d -p 8000:8000 -e TUSHARE_TOKEN=你的token tushare-mcp
```

## 故障排查

### Token 无效
```bash
# 测试 Token（使用 tinyshare）
python3 << EOF
import tinyshare as ts
ts.set_token('你的token')
print(ts.pro_api().stock_basic(ts_code='000001.SZ'))
EOF
```

### 服务无法访问
```bash
# 检查服务状态
ps aux | grep server.py

# 检查端口占用
lsof -i :8000
```

### MCP 连接失败
```bash
# 测试端点
curl http://localhost:8000/
curl http://localhost:8000/sse
```

## License

MIT
