Content
# Tushare MCP HTTP
Based on [Tushare Pro](https://tushare.pro), the MCP server provides HTTP transport protocol support, allowing AI assistants to access financial data through the MCP protocol.
## Project Introduction
`tushare-mcp-http` is an MCP (Model Context Protocol) server developed based on the FastMCP framework, providing Tushare financial data interfaces for AI assistants through the HTTP protocol. This project supports querying various financial data, including A-shares, indices, funds, futures, bonds, Hong Kong stocks, US stocks, and macroeconomic data.
## Features
- 🚀 **HTTP Transport Protocol** - Supports streamable-http transport, suitable for remote deployment
- 🔐 **API Key Authentication** - Supports Bearer Token authentication, protecting API security
- 📊 **Rich Data Types** - Covers stocks, indices, funds, futures, bonds, Hong Kong stocks, US stocks, and macroeconomic data
- 🔧 **Modular Design** - Clear code structure, separated by data type modules
- 🛠️ **General Query Interface** - Arbitrary Tushare API can be called through the `tushare_query` tool
- 📚 **Complete Interface Documentation** - Built-in API list and documentation query tools
## Project Structure
```
tushare-mcp-http/
├── tushare_mcp_http/ # Main package directory
│ ├── __init__.py # Package initialization file
│ ├── __main__.py # Command-line entry
│ ├── server.py # Server main module
│ ├── auth.py # Authentication middleware module
│ ├── config.py # Configuration management module
│ ├── py.typed # Type hint marker file
│ └── tools/ # Tool module directory
│ ├── __init__.py # Tool module initialization
│ ├── base.py # Basic tools (formatting functions)
│ ├── common.py # General tools
│ ├── stock.py # Stock tools
│ ├── index.py # Index tools
│ ├── fund.py # Fund tools
│ ├── futures.py # Futures tools
│ ├── bond.py # Bond tools
│ ├── hk_stock.py # Hong Kong stock tools
│ ├── us_stock.py # US stock tools
│ └── macro.py # Macroeconomic tools
├── pyproject.toml # Project configuration file
├── requirements.txt # Dependency list
└── README.md # Project documentation
```
## Installation
### Install via pip
**Linux/macOS/Windows PowerShell/Windows CMD:**
```bash
pip install tushare-mcp-http
```
### Install from source
**Linux/macOS/Windows PowerShell/Windows CMD:**
```bash
git clone https://github.com/duhanjun/tushare-mcp-http.git
cd tushare-mcp-http
pip install -e .
```
## Configuration
### 1. Obtain Tushare Token
Register an account on the [Tushare website](https://tushare.pro/register) and obtain the API token.
### 2. Configure environment variables
```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. Authentication configuration (optional)
The server enables API Key authentication by default. If no custom API Key is defined, a random API Key will be generated during startup.
**Custom API Key (recommended):**
**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
```
**Disable authentication (not recommended, only for internal testing):**
**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. Other configurations (optional)
**Linux/macOS:**
```bash
export MCP_HOST=0.0.0.0 # Service address, default 0.0.0.0
export MCP_PORT=8000 # Service port, default 8000
export MCP_PATH=/mcp # Service path, default /mcp
```
**Windows PowerShell:**
```powershell
$env:MCP_HOST = "0.0.0.0" # Service address, default 0.0.0.0
$env:MCP_PORT = "8000" # Service port, default 8000
$env:MCP_PATH = "/mcp" # Service path, default /mcp
```
**Windows CMD:**
```cmd
set MCP_HOST=0.0.0.0 # Service address, default 0.0.0.0
set MCP_PORT=8000 # Service port, default 8000
set MCP_PATH=/mcp # Service path, default /mcp
```
## Usage
### Start the server
**Linux/macOS:**
```bash
tushare-mcp-http
```
**Windows PowerShell:**
```powershell
tushare-mcp-http
```
**Windows CMD:**
```cmd
tushare-mcp-http
```
After starting, it will display:
```
Starting tushare-mcp-http...
Tushare Token: your_toke***
Server address: http://0.0.0.0:8000/mcp
Authentication: Enabled
API Key: xxxxxxxx...xxxx
```
> ⚠️ **Important**: Please keep the API Key displayed during startup secure. Clients need to use it when connecting.
### MCP client configuration
Add the following configuration to your MCP client:
**Authenticated configuration (recommended):**
```json
{
"mcpServers": {
"tushare": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}
```
**Unauthenticated configuration** (need to set `MCP_AUTH_ENABLED=false`):
```json
{
"mcpServers": {
"tushare": {
"url": "http://localhost:8000/mcp"
}
}
}
```
## Available Tools
### General Tools
| Tool Name | Description |
| ----------------- | ------------------- |
| `tushare_query` | General Tushare API query interface |
| `get_api_list` | Get supported API interface list |
| `get_api_doc` | Get documentation for a specified API |
| `test_connection` | Test Tushare API connection status |
### Stock Tools
| Tool Name | Description |
| ------------------------- | ----------------- |
| `get_stock_list` | Get stock basic list |
| `get_trade_calendar` | Get trading calendar |
| `get_daily_quote` | Get daily quote data |
| `get_weekly_quote` | Get weekly quote data |
| `get_monthly_quote` | Get monthly quote data |
| `get_daily_basic` | Get daily basic data（PE、PB、market value, etc.） |
| `get_adj_factor` | Get adjustment factor |
| `get_suspend_info` | Get suspension and resumption information |
| `get_income_statement` | Get income statement data |
| `get_balance_sheet` | Get balance sheet data |
| `get_cashflow_statement` | Get cash flow statement data |
| `get_financial_indicator` | Get financial indicator data |
| `get_forecast` | Get earnings forecast data |
| `get_express` | Get earnings express data |
| `get_dividend` | Get dividend data |
| `get_top10_holders` | Get top 10 shareholders data |
| `get_top10_floatholders` | Get top 10 floating shareholders data |
| `get_share_number` | Get shareholder number data |
| `get_margin_detail` | Get margin trading detail |
### Index Tools
| Tool Name | Description |
| ---------------------- | --------- |
| `get_index_basic` | Get index basic information |
| `get_index_daily` | Get index daily quote |
| `get_index_weekly` | Get index weekly quote |
| `get_index_monthly` | Get index monthly quote |
| `get_index_weight` | Get index constituent weight |
| `get_index_dailybasic` | Get index daily basic data |
| `get_index_classify` | Get index classification |
### Fund Tools
| Tool Name | Description |
| -------------------- | ---------- |
| `get_fund_basic` | Get fund basic information |
| `get_fund_nav` | Get fund NAV data |
| `get_fund_daily` | Get fund daily quote |
| `get_fund_adj` | Get fund adjustment data |
| `get_fund_div` | Get fund dividend data |
| `get_fund_portfolio` | Get fund portfolio data |
| `get_fund_manager` | Get fund manager information |
| `get_fund_company` | Get fund company information |
| `get_fund_share` | Get fund share data |
### Futures Tools
| Tool Name | Description |
| --------------------- | ----------- |
| `get_fut_basic` | Get futures contract basic information |
| `get_fut_daily` | Get futures daily quote |
| `get_fut_mins` | Get futures minute data |
| `get_fut_holding` | Get futures holding data |
| `get_fut_settle` | Get futures settlement parameter |
| `get_fut_mapping` | Get futures main contract mapping |
| `get_fut_wsr` | Get futures warehouse receipt data |
| `get_index_fut_daily` | Get stock index futures daily quote |
### Bond Tools
| Tool Name | Description |
| ------------------ | --------- |
| `get_cb_basic` | Get convertible bond basic information |
| `get_cb_daily` | Get convertible bond daily quote |
| `get_cb_issue` | Get convertible bond issuance information |
| `get_cb_price_chg` | Get convertible bond price change |
| `get_cb_share` | Get convertible bond conversion data |
| `get_bond_basic` | Get bond basic information |
| `get_bond_daily` | Get bond daily quote |
### Hong Kong Stock Tools
| Tool Name | Description |
| --------------------- | --------- |
| `get_hk_basic` | Get Hong Kong stock basic information |
| `get_hk_daily` | Get Hong Kong stock daily quote |
| `get_hk_hold` | Get Hong Kong stock holding data |
| `get_hk_income` | Get Hong Kong stock income statement |
| `get_hk_balancesheet` | Get Hong Kong stock balance sheet |
| `get_hk_cashflow` | Get Hong Kong stock cash flow statement |
### US Stock Tools
| Tool Name | Description |
| --------------------- | --------- |
| `get_us_basic` | Get US stock basic information |
| `get_us_daily` | Get US stock daily quote |
| `get_us_adj` | Get US stock adjustment factor |
| `get_us_income` | Get US stock income statement |
| `get_us_balancesheet` | Get US stock balance sheet |
| `get_us_cashflow` | Get US stock cash flow statement |
### Macroeconomic Tools
| Tool Name | Description |
| ------------------ | -------------------- |
| `get_cn_cpi` | Get China CPI consumer price index |
| `get_cn_ppi` | Get China PPI producer price index |
| `get_cn_gdp` | Get China GDP gross domestic product |
| `get_cn_pmi` | Get China PMI purchasing manager index |
| `get_cn_m` | Get China money supply |
| `get_shibor` | Get Shanghai Interbank Offered Rate |
| `get_shibor_quote` | Get Shibor quote data |
| `get_lpr` | Get loan market quotation rate |
| `get_libor` | Get London Interbank Offered Rate |
| `get_hibor` | Get Hong Kong Interbank Offered Rate |
## Interactive Example
After installation and configuration, you can interact with the AI assistant using natural language through the MCP client:
**Get stock data**:
```
Get the stock price data of Ping An Bank for the past 30 days
```
**Financial analysis**:
```
View the recent financial report of China Merchants Bank and analyze revenue and net profit
```
**Index data**:
```
Get the recent quote data of the Shanghai Composite Index
```
**Macroeconomic data**:
```
Query the GDP and CPI data for the past year
```
**General query**:
```
Use tushare_query to query the dragon and tiger list data
```
## Parameter Format Description
- **Date format**: YYYYMMDD (e.g., 20241231)
- **Stock code**: ts\_code format (e.g., 000001.SZ, 600000.SH)
- **Return format**: JSON format, containing success, data, count, and columns fields
## Development Guide
### Local Development
```bash
# Clone the project
git clone https://github.com/duhanjun/tushare-mcp-http.git
cd tushare-mcp-http
# Install development dependencies
pip install -e ".[dev]"
# Run the service
python -m tushare_mcp_http.server
```
### Packaging and Release
```bash
# Install packaging tools
pip install build twine
# Package
python -m build
# Upload to PyPI
twine upload dist/*
```
## Environment Variables
| Variable Name | Description | Default Value |
| ------------------ | ------------------- | ------------------ |
| `TUSHARE_TOKEN` | Tushare API token | Required |
| `MCP_HOST` | Server listening address | `0.0.0.0` |
| `MCP_PORT` | Server listening port | `8000` |
| `MCP_PATH` | MCP service path | `/mcp` |
| `MCP_NAME` | Service name | `tushare-mcp-http` |
| `MCP_API_KEY` | API authentication key | Automatically generate 32-bit random key |
| `MCP_AUTH_ENABLED` | Enable authentication (true/false) | `true` |
## Related Links
- [Tushare Pro website](https://tushare.pro/)
- [Tushare API documentation](https://tushare.pro/document/2)
- [MCP protocol documentation](https://modelcontextprotocol.io/)
- [FastMCP framework](https://github.com/jlowin/fastmcp)
## License
MIT License
## Notes
- This project is for learning and research purposes only
- API calls have frequency limits, please use reasonably
- Data source: Tushare, please do not use for commercial purposes
