# tushare-mcp-server

[中文文档](README_CN.md) | English

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Tushare Pro](https://tushare.pro) financial data API. Provides AI assistants (GitHub Copilot, Claude, etc.) with direct access to comprehensive Chinese financial market data — covering A-shares, indices, funds, futures, options, bonds, forex, HK/US stocks, and macroeconomic indicators.

## Features

- **Universal Query** — `tushare_query` calls any of the 173 Tushare Pro APIs
- **15 Convenience Tools** — Pre-built tools for stocks, indices, financials, funds, and more
- **Built-in Documentation** — `get_api_doc` / `search_api_docs` for API parameter lookup
- **Categorized Index** — 173 APIs organized into 18 categories

### Data Coverage

| Category | # | Examples |
|----------|---|----------|
| A-Shares | 37 | stock_basic, daily, weekly, monthly, daily_basic, adj_factor, pro_bar |
| Financials | 9 | income, balancesheet, cashflow, fina_indicator, forecast |
| Market Reference | 23 | margin, top_list, block_trade, hsgt_top10, pledge_stat |
| Indices | 13 | index_basic, index_daily, index_weight, sw_daily, ci_daily |
| Money Flow | 8 | moneyflow, moneyflow_hsgt, moneyflow_ind_ths |
| Funds | 14 | fund_basic, fund_nav, fund_daily, etf_basic, fund_portfolio |
| Futures | 8 | fut_basic, fut_daily, fut_holding, fut_mapping |
| Options | 3 | opt_basic, opt_daily, opt_mins |
| Bonds / CB | 9 | cb_basic, cb_daily, cb_issue, repo_daily, yc_cb |
| HK Stocks | 9 | hk_basic, hk_daily, hk_income, hk_balancesheet |
| US Stocks | 8 | us_basic, us_daily, us_income, us_balancesheet |
| Macro Economy | 14 | shibor, cn_gdp, cn_cpi, cn_ppi, cn_pmi, libor |
| Sector / Concept | 5 | ths_index, ths_daily, dc_index, dc_member |
| Others | 13 | fx_daily, sge_daily, news, trade_cal, etc. |

## Prerequisites

- Python 3.10+
- A [Tushare Pro](https://tushare.pro/register?invited_code=ANNJLJ) account and API token

## Quick Start

### Install via npx (recommended)

No installation needed — just configure your MCP client:

```json
{
  "servers": {
    "tushare": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tushare-mcp-server"],
      "env": { "TUSHARE_TOKEN": "your_token_here" }
    }
  }
}
```

### Install from source

```bash
git clone https://github.com/erwanjun/tushare-mcp-server.git
cd tushare-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install mcp httpx
```

## Configuration

### Tushare Token

Set your token via any of these methods:

1. **`.env` file** (recommended) — create `.env` in the project root:
   ```
   TUSHARE_TOKEN=your_token_here
   ```
2. **Environment variable** — `export TUSHARE_TOKEN=your_token`
3. **MCP client config** — pass via the `env` field (see examples below)

### VS Code (GitHub Copilot)

`.vscode/mcp.json`:

```json
{
  "servers": {
    "tushare": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tushare-mcp-server"],
      "env": { "TUSHARE_TOKEN": "your_token_here" }
    }
  }
}
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tushare": {
      "command": "npx",
      "args": ["-y", "tushare-mcp-server"],
      "env": { "TUSHARE_TOKEN": "your_token_here" }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `tushare_query` | Universal query — call any Tushare Pro API |
| `get_stock_list` | A-share stock list |
| `get_trade_calendar` | Trading calendar |
| `get_daily_bars` | Daily OHLCV (unadjusted) |
| `get_daily_basic` | Daily indicators: PE, PB, market cap, turnover |
| `get_income` | Income statement |
| `get_balancesheet` | Balance sheet |
| `get_cashflow` | Cash flow statement |
| `get_fina_indicator` | Financial indicators (ROE, ROA, margins) |
| `get_index_daily` | Index daily bars |
| `get_moneyflow` | Stock money flow |
| `get_concept` | Concept / sector classification |
| `get_concept_detail` | Concept constituents |
| `get_fund_basic` | Fund list |
| `get_fund_nav` | Fund NAV |
| `get_shibor` | Shibor interest rates |
| `get_api_doc` | Full API documentation by endpoint name |
| `search_api_docs` | Search API docs by keyword |

## Development

```bash
# Re-crawl Tushare documentation
python crawl_docs.py

# Rebuild API index
python build_index.py
```

## License

MIT