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)

Installation

Install the dependencies:

pip install -r requirements.txt

Configuration

Create a .env file in the project root directory:
```
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.

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).
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.

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.
```
{
  "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.
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:

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.

{
  "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 新增了两个期权工具：

get_option_basic(exchange, fields): 返回上/深交所上市期权的合约元数据（行权价、类型、到期日等）。
get_option_daily(ts_code, trade_date, start_date, end_date, exchange): 返回期权日线行情。

示例（通过 MCP 调用 get_option_daily 查询科创50期权在单日的 K 线）：

{
  "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/场内基金的日线行情：

{
  "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）获取，模拟“车轮饼”策略：

每个自然月首个交易日：

若空仓，卖出 5%~10% OTM 的认沽合约（call_put='P'）。
若持仓，卖出 5%~10% OTM 的认购合约（call_put='C'）。

到期日根据标的收盘价判断是否被指派，按轮动逻辑更新持仓。
统计权利金、被指派次数、最大保证金占用，并估算收益率。
报告会显示每笔交易的隐含波动率：若 Tushare 返回该字段则直接使用，否则基于 Black-Scholes（假定 2% 无风险利率）用成交价反推出一个参考值。

运行：

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：

{
  "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 及固定权重构建组合，并在每个自然月首个交易日动态再平衡：

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:

{
  "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.