# Tushare MCP Server
This is a Model Context Protocol (MCP) server that provides access to Tushare financial data.
## Prerequisites
- Python 3.10 or higher
- A Tushare Token (Get it from [Tushare.pro](https://tushare.pro/))
## Installation
1. Install the dependencies:
```bash
pip install -r requirements.txt
```
## Configuration
1. Create a `.env` file in the project root directory:
```env
TUSHARE_TOKEN=your_tushare_token_here
```
## Project Layout
- `server/`: MCP entrypoint (`server.py`) plus logs.
- `src/`: application code split into `strategies/` (wheel backtest, etc.) and `utils/` (shared math + performance helpers).
- `temp_data/`: generated artifacts such as `wheel_report.html`, `wheel_dashboard.html`, and portfolio CSV/JSON outputs.
- `tests/`: standalone scripts for strategy prototyping (`wheel_strategy.py`, `portfolio_rebalance.py`, etc.).
## Using with GitHub Copilot in VS Code
To use this MCP server with GitHub Copilot in VS Code, you need to configure the `mcp.json` file.
1. **Open Configuration**:
* Open the Command Palette (`Ctrl+Shift+P` or `F1`).
* Search for and select **`MCP: Configure MCP Servers`**.
* This will open the `mcp.json` file (typically located in `%APPDATA%\Code\User\mcp.json` on Windows).
2. **Add via Command Palette (quick way)**:
* Press `Ctrl+Shift+P` again and pick **`MCP: Add MCP Server`**.
* When the **Enter Command** prompt appears, paste:
```
C:\Users\lochen\AppData\Local\Microsoft\WindowsApps\python3.13.exe c:\Users\lochen\tushare-mcp\server\server.py
```
* Accept the suggested server name (for example `tushare`) and save.
3. **Add Server Configuration manually**:
Add the `tushare-server` configuration to the JSON file. Make sure to use absolute paths for both the Python executable and the script.
```json
{
"mcpServers": {
"tushare-server": {
"command": "C:\\path\\to\\your\\python.exe",
"args": [
"C:\\path\\to\\tushare_mcp_server\\server\\server.py"
]
}
}
}
```
* Replace `C:\\path\\to\\your\\python.exe` with your actual Python interpreter path (e.g., `C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python311\\python.exe`).
* Replace `C:\\path\\to\\tushare_mcp_server\\server\\server.py` with the absolute path to this project's server entry point.
3. **Restart VS Code**:
After saving `mcp.json`, restart VS Code for the changes to take effect.
## Usage
### Testing with MCP Inspector
You can test the server using the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector python server/server.py
```
### Price Volatility Tool
After the server is running (Inspector, Copilot, etc.), invoke the `get_price_volatility` tool to compute recent volatility for a stock. It supports `frequency` values `daily`, `monthly`, or `yearly`, letting you measure 波动率 on日线/月线/年线 data.
```json
{
"tool": "get_price_volatility",
"args": {
"identifier": "000001.SZ",
"window": 30,
"frequency": "daily",
"annualize": true
}
}
```
Key fields returned:
- `frequency`: 数据频率（daily/monthly/yearly）。
- `window_periods`: 实际使用的周期数（交易日/月份/年份）。
- `period_volatility`: 该频率下的标准差。
- `annualized_volatility`: 根据频率自动换算后的年化波动率（252/12/1）。
- `mean_period_return`: 平均单周期收益。
### Option Reference & Daily Data
基于 [Tushare 文档 #157](https://tushare.pro/document/2?doc_id=157) 新增了两个期权工具：
- `get_option_basic(exchange, fields)`: 返回上/深交所上市期权的合约元数据（行权价、类型、到期日等）。
- `get_option_daily(ts_code, trade_date, start_date, end_date, exchange)`: 返回期权日线行情。
示例（通过 MCP 调用 `get_option_daily` 查询科创50期权在单日的 K 线）：
```json
{
"tool": "get_option_daily",
"args": {
"exchange": "SSE",
"trade_date": "20251203"
}
}
```
返回值为 JSON 数组，字段与 Tushare `opt_daily` 接口一致，可配合 `get_price_volatility` 等工具进一步分析期权策略。
### ETF/Fund Daily Quotes
使用新的 `get_fund_daily` 工具（Tushare 文档 #127 对应接口）可直接拉取 ETF/场内基金的日线行情：
```json
{
"tool": "get_fund_daily",
"args": {
"ts_code": "159915.SZ",
"start_date": "20250101",
"end_date": "20251203",
"fields": "ts_code,trade_date,open,high,low,close,vol"
}
}
```
当 `fields` 为空时会返回默认全部列。可搭配 `get_option_daily`、`get_price_volatility` 等工具构建 ETF+期权策略分析。
### Wheel Strategy Backtest
`tests/wheel_strategy.py` 利用 `159915.SZ`（创业板ETF）及其期权，ETF 行情通过 Tushare `fund_daily` 接口（[文档 #127](https://tushare.pro/document/2?doc_id=127)）获取，模拟“车轮饼”策略：
1. 每个自然月首个交易日：
- 若空仓，卖出 5%~10% OTM 的认沽合约（`call_put='P'`）。
- 若持仓，卖出 5%~10% OTM 的认购合约（`call_put='C'`）。
2. 到期日根据标的收盘价判断是否被指派，按轮动逻辑更新持仓。
3. 统计权利金、被指派次数、最大保证金占用，并估算收益率。
4. 报告会显示每笔交易的隐含波动率：若 Tushare 返回该字段则直接使用，否则基于 Black-Scholes（假定 2% 无风险利率）用成交价反推出一个参考值。
运行：
```bash
python tests/wheel_strategy.py
```
输出包含总收益、占用保证金、近10期交易记录等。所有生成的 `wheel_report.html`、`wheel_dashboard.html` 等文件都会写入 `temp_data/`，便于统一清理。若需调整标的、时间区间或虚值区间，可编辑脚本顶部的常量（`UNDERLYING`、`START_DATE`、`OTM_RANGE` 等）。
### Wheel Strategy MCP Tool
无需运行脚本，也可直接通过 MCP 调用 `backtest_wheel_strategy`：
```json
{
"tool": "backtest_wheel_strategy",
"args": {
"underlying": "159915.SZ",
"start_date": "20230101",
"end_date": "20251203",
"otm_min": 0.05,
"otm_max": 0.10,
"initial_capital": 30000
}
}
```
返回 JSON 中包含：
- `ending_value`、`return_on_capital`、`annualized_return` 等指标。
- `recent_trades`：近 12 期的期权选择、权利金、行权价及是否被指派。
可通过参数更换标的（只要该 ETF 有挂牌期权）、调整虚值区间或回测时间窗。确保 Tushare Token 对 `fund_daily`、`opt_basic`、`opt_daily` 接口有权限。
### Multi-ETF Portfolio Backtest
`tests/portfolio_rebalance.py` 按照截图中的 10 只 ETF 及固定权重构建组合，并在每个自然月首个交易日动态再平衡：
```bash
python tests/portfolio_rebalance.py
```
脚本会：
- 自动获取所有 ETF 的可用历史区间，并截取重叠部分；
- 计算每日组合净值并输出 `temp_data/portfolio_equity_curve.csv`，再平衡明细写入 `temp_data/portfolio_rebalances.csv`；
- 生成 `temp_data/portfolio_vs_benchmarks.csv`，其中包含组合与沪深300/中证500/创业板指的归一化指数曲线；
- 在 `temp_data/portfolio_summary.json` 中汇总收益率、年化波动率、最大回撤、Sharpe Ratio 及各基准指数的对比指标。
### Using with Claude Desktop
Add the following configuration to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"tushare": {
"command": "python",
"args": ["C:\\Users\\lochen\\tushare_mcp_server\\server\\server.py"],
"env": {
"TUSHARE_TOKEN": "your_token_here"
}
}
}
}
```
Make sure to replace `your_token_here` with your actual Tushare token.
