# tushare-mcp-http

基于 [Tushare Pro](https://tushare.pro) 的 MCP 服务器，提供 HTTP 传输协议支持，让 AI 助手能够通过 MCP 协议获取金融数据。

## 项目简介

tushare-mcp-http 是一个基于 FastMCP 框架开发的 MCP（Model Context Protocol）服务器，通过 HTTP 协议为 AI 助手提供 Tushare 金融数据接口。该项目支持多种金融数据的查询，包括 A 股、指数、基金、期货、债券、港股、美股以及宏观经济数据等。

## 特性

- 🚀 **HTTP 传输协议** - 支持 streamable-http 传输，适合远程部署
- 🔐 **API Key 认证** - 支持 Bearer Token 认证，保护 API 安全
- 📊 **丰富的数据类型** - 覆盖股票、指数、基金、期货、债券、港股、美股、宏观经济等
- 🔧 **模块化设计** - 清晰的代码结构，按数据类型分离模块
- 🛠️ **通用查询接口** - 通过 `tushare_query` 工具可调用任意 Tushare API
- 📚 **完整的接口文档** - 内置 API 列表和文档查询工具

## 项目结构

```
tushare-mcp-http/
├── tushare_mcp_http/           # 主包目录
│   ├── __init__.py            # 包初始化文件
│   ├── __main__.py            # 命令行入口
│   ├── server.py              # 服务器主模块
│   ├── auth.py                # 认证中间件模块
│   ├── config.py              # 配置管理模块
│   ├── py.typed               # 类型提示标记文件
│   └── tools/                 # 工具模块目录
│       ├── __init__.py        # 工具模块初始化
│       ├── base.py            # 基础工具（格式化函数）
│       ├── common.py          # 通用工具
│       ├── stock.py           # 股票工具
│       ├── index.py           # 指数工具
│       ├── fund.py            # 基金工具
│       ├── futures.py         # 期货工具
│       ├── bond.py            # 债券工具
│       ├── hk_stock.py        # 港股工具
│       ├── us_stock.py        # 美股工具
│       └── macro.py           # 宏观经济工具
├── pyproject.toml             # 项目配置文件
├── requirements.txt           # 依赖列表
└── README.md                  # 项目文档
```

## 安装

### 通过 pip 安装

**Linux/macOS/Windows PowerShell/Windows CMD:**
```bash
pip install tushare-mcp-http
```

### 从源码安装

**Linux/macOS/Windows PowerShell/Windows CMD:**
```bash
git clone https://github.com/duhanjun/tushare-mcp-http.git
cd tushare-mcp-http
pip install -e .
```

## 配置

### 1. 获取 Tushare Token

到 [Tushare 官网](https://tushare.pro/register) 注册账号并获取 API token。

### 2. 配置环境变量

```bash
# Linux/macOS
export TUSHARE_TOKEN="your_token_here"

# Windows PowerShell
$env:TUSHARE_TOKEN = "your_token_here"

# Windows CMD
set TUSHARE_TOKEN=your_token_here
```

### 3. 认证配置（可选）

服务器默认启用 API Key 认证，未自定义 API Key 时，启动时会自动生成一个随机 API Key。

**自定义 API Key（推荐）:**

**Linux/macOS:**
```bash
export MCP_API_KEY="your_secure_api_key_here"
```

**Windows PowerShell:**
```powershell
$env:MCP_API_KEY = "your_api_key_here"
```

**Windows CMD:**
```cmd
set MCP_API_KEY=your_api_key_here
```

**禁用认证（不推荐，仅限内网测试）:**

**Linux/macOS:**
```bash
export MCP_AUTH_ENABLED=false
```

**Windows PowerShell:**
```powershell
$env:MCP_AUTH_ENABLED = "false"
```

**Windows CMD:**
```cmd
set MCP_AUTH_ENABLED=false
```

### 4. 其他配置（可选）

**Linux/macOS:**
```bash
export MCP_HOST=0.0.0.0      # 服务地址，默认 0.0.0.0
export MCP_PORT=8000          # 服务端口，默认 8000
export MCP_PATH=/mcp          # 服务路径，默认 /mcp
```

**Windows PowerShell:**
```powershell
$env:MCP_HOST = "0.0.0.0"    # 服务地址，默认 0.0.0.0
$env:MCP_PORT = "8000"       # 服务端口，默认 8000
$env:MCP_PATH = "/mcp"       # 服务路径，默认 /mcp
```

**Windows CMD:**
```cmd
set MCP_HOST=0.0.0.0         # 服务地址，默认 0.0.0.0
set MCP_PORT=8000            # 服务端口，默认 8000
set MCP_PATH=/mcp            # 服务路径，默认 /mcp
```

## 使用方法

### 启动服务器

**Linux/macOS:**
```bash
tushare-mcp-http
```

**Windows PowerShell:**
```powershell
tushare-mcp-http
```

**Windows CMD:**
```cmd
tushare-mcp-http
```

启动后会显示：

```
正在启动 tushare-mcp-http...
Tushare Token: your_toke***
服务器地址: http://0.0.0.0:8000/mcp
认证: 已启用
API Key: xxxxxxxx...xxxx
```

> ⚠️ **重要**：请妥善保管启动时显示的 API Key，客户端连接时需要使用。

### MCP 客户端配置

将以下配置添加到您的 MCP 客户端：

**带认证的配置（推荐）**：

```json
{
  "mcpServers": {
    "tushare": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}
```

**无认证的配置**（需设置 `MCP_AUTH_ENABLED=false`）：

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

## 可用工具

### 通用工具

| 工具名               | 描述                  |
| ----------------- | ------------------- |
| `tushare_query`   | 通用 Tushare API 查询接口 |
| `get_api_list`    | 获取支持的 API 接口列表      |
| `get_api_doc`     | 获取指定 API 的文档说明      |
| `test_connection` | 测试 Tushare API 连接状态 |

### 股票工具

| 工具名                       | 描述                |
| ------------------------- | ----------------- |
| `get_stock_list`          | 获取股票基础列表          |
| `get_trade_calendar`      | 获取交易日历            |
| `get_daily_quote`         | 获取日线行情数据          |
| `get_weekly_quote`        | 获取周线行情数据          |
| `get_monthly_quote`       | 获取月线行情数据          |
| `get_daily_basic`         | 获取每日指标（PE、PB、市值等） |
| `get_adj_factor`          | 获取复权因子            |
| `get_suspend_info`        | 获取停复牌信息           |
| `get_income_statement`    | 获取利润表数据           |
| `get_balance_sheet`       | 获取资产负债表数据         |
| `get_cashflow_statement`  | 获取现金流量表数据         |
| `get_financial_indicator` | 获取财务指标数据          |
| `get_forecast`            | 获取业绩预告数据          |
| `get_express`             | 获取业绩快报数据          |
| `get_dividend`            | 获取分红送股数据          |
| `get_top10_holders`       | 获取前十大股东数据         |
| `get_top10_floatholders`  | 获取前十大流通股东数据       |
| `get_share_number`        | 获取股东人数数据          |
| `get_margin_detail`       | 获取融资融券交易明细        |

### 指数工具

| 工具名                    | 描述        |
| ---------------------- | --------- |
| `get_index_basic`      | 获取指数基础信息  |
| `get_index_daily`      | 获取指数日线行情  |
| `get_index_weekly`     | 获取指数周线行情  |
| `get_index_monthly`    | 获取指数月线行情  |
| `get_index_weight`     | 获取指数成分股权重 |
| `get_index_dailybasic` | 获取指数每日指标  |
| `get_index_classify`   | 获取指数分类    |

### 基金工具

| 工具名                  | 描述         |
| -------------------- | ---------- |
| `get_fund_basic`     | 获取基金基础信息   |
| `get_fund_nav`       | 获取基金净值数据   |
| `get_fund_daily`     | 获取场内基金日线行情 |
| `get_fund_adj`       | 获取基金复权数据   |
| `get_fund_div`       | 获取基金分红数据   |
| `get_fund_portfolio` | 获取基金持仓数据   |
| `get_fund_manager`   | 获取基金经理信息   |
| `get_fund_company`   | 获取基金公司信息   |
| `get_fund_share`     | 获取基金份额数据   |

### 期货工具

| 工具名                   | 描述          |
| --------------------- | ----------- |
| `get_fut_basic`       | 获取期货合约基础信息  |
| `get_fut_daily`       | 获取期货日线行情    |
| `get_fut_mins`        | 获取期货分钟行情    |
| `get_fut_holding`     | 获取期货持仓数据    |
| `get_fut_settle`      | 获取期货结算参数    |
| `get_fut_mapping`     | 获取主力与连续合约映射 |
| `get_fut_wsr`         | 获取仓单日报数据    |
| `get_index_fut_daily` | 获取股指期货日线行情  |

### 债券工具

| 工具名                | 描述        |
| ------------------ | --------- |
| `get_cb_basic`     | 获取可转债基础信息 |
| `get_cb_daily`     | 获取可转债日线行情 |
| `get_cb_issue`     | 获取可转债发行信息 |
| `get_cb_price_chg` | 获取可转债价格变动 |
| `get_cb_share`     | 获取可转债转股数据 |
| `get_bond_basic`   | 获取债券基础信息  |
| `get_bond_daily`   | 获取债券日线行情  |

### 港股工具

| 工具名                   | 描述        |
| --------------------- | --------- |
| `get_hk_basic`        | 获取港股基础信息  |
| `get_hk_daily`        | 获取港股日线行情  |
| `get_hk_hold`         | 获取港股通持股数据 |
| `get_hk_income`       | 获取港股利润表   |
| `get_hk_balancesheet` | 获取港股资产负债表 |
| `get_hk_cashflow`     | 获取港股现金流量表 |

### 美股工具

| 工具名                   | 描述        |
| --------------------- | --------- |
| `get_us_basic`        | 获取美股基础信息  |
| `get_us_daily`        | 获取美股日线行情  |
| `get_us_adj`          | 获取美股复权因子  |
| `get_us_income`       | 获取美股利润表   |
| `get_us_balancesheet` | 获取美股资产负债表 |
| `get_us_cashflow`     | 获取美股现金流量表 |

### 宏观工具

| 工具名                | 描述                   |
| ------------------ | -------------------- |
| `get_cn_cpi`       | 获取中国 CPI 居民消费价格指数    |
| `get_cn_ppi`       | 获取中国 PPI 工业生产者出厂价格指数 |
| `get_cn_gdp`       | 获取中国 GDP 国内生产总值      |
| `get_cn_pmi`       | 获取中国 PMI 采购经理指数      |
| `get_cn_m`         | 获取中国货币供应量            |
| `get_shibor`       | 获取上海银行间同业拆放利率        |
| `get_shibor_quote` | 获取 Shibor 报价数据       |
| `get_lpr`          | 获取贷款市场报价利率           |
| `get_libor`        | 获取伦敦银行间同业拆借利率        |
| `get_hibor`        | 获取香港银行间同业拆借利率        |

## 交互示例

安装并配置后，您可以通过 MCP 客户端用自然语言与 AI 助手交互：

**获取股票数据**：

```
获取平安银行最近 30 天的股价数据
```

**财务分析**：

```
查看招商银行最近的财务报表，分析营收和净利润
```

**指数数据**：

```
获取上证指数最近的行情数据
```

**宏观数据**：

```
查询最近一年的 GDP 和 CPI 数据
```

**通用查询**：

```
使用 tushare_query 查询龙虎榜数据
```

## 参数格式说明

- **日期格式**：YYYYMMDD（如 20241231）
- **股票代码**：ts\_code 格式（如 000001.SZ, 600000.SH）
- **返回格式**：JSON 格式，包含 success、data、count、columns 字段

## 开发指南

### 本地开发

```bash
# 克隆项目
git clone https://github.com/duhanjun/tushare-mcp-http.git
cd tushare-mcp-http

# 安装开发依赖
pip install -e ".[dev]"

# 运行服务
python -m tushare_mcp_http.server
```

### 打包发布

```bash
# 安装打包工具
pip install build twine

# 打包
python -m build

# 上传到 PyPI
twine upload dist/*
```

## 环境变量

| 变量名                | 描述                  | 默认值                |
| ------------------ | ------------------- | ------------------ |
| `TUSHARE_TOKEN`    | Tushare API token   | 必填                 |
| `MCP_HOST`         | 服务器监听地址             | `0.0.0.0`          |
| `MCP_PORT`         | 服务器监听端口             | `8000`             |
| `MCP_PATH`         | MCP 服务路径            | `/mcp`             |
| `MCP_NAME`         | 服务名称                | `tushare-mcp-http` |
| `MCP_API_KEY`      | API 认证密钥            | 自动生成 32 位随机密钥      |
| `MCP_AUTH_ENABLED` | 是否启用认证（true/false） | `true`             |

## 相关链接

- [Tushare Pro 官网](https://tushare.pro/)
- [Tushare API 文档](https://tushare.pro/document/2)
- [MCP 协议文档](https://modelcontextprotocol.io/)
- [FastMCP 框架](https://github.com/jlowin/fastmcp)

## 许可证

MIT License

## 注意事项

- 本项目仅供学习和研究使用
- API 调用有频率限制，请合理使用
- 数据来源于 Tushare，请勿用于商业用途