Content
# shfe-gold-mcp
This project is a _Model Content Protocol_ (MCP) server + Streamlit quantitative workbench focused on **Shanghai Futures Exchange Gold Futures Main Contract (AU)**.
It integrates three levels of market data: Shanghai Gold, COMEX GC, and XAU/USD, synchronously extracts **MCP intraday behavior signals**, and provides backtesting, reporting, and API services, aiming to answer all questions related to intraday trading patterns of Shanghai Gold.
---
## Project Structure
```
shfe_gold_mcp/
│
├── app.py # Streamlit application entry point
├── pyproject.toml # Dependency list
├── README.md # Project description
│
├── assets/ # Static resources
│ └── logo.svg # Project logo
│
├── .streamlit/ # Streamlit configuration
│ └── config.toml # Theme configuration
│
├── data_fetchers/ # Data fetching
│ ├── alpha_vantage.py # XAU/USD data source
│ ├── tushare_fetcher.py # AU main contract data source
│ └── yfinance_fetcher.py # COMEX GC data source
│
├── data_processing/ # Data processing
│ ├── cleaner.py # Data cleaning
│ └── continuous_stitcher.py # Contract stitching
│
├── indicators/ # Technical indicators
│ ├── technical.py # Indicators like MACD, VWAP, etc.
│ └── orderflow.py # Order flow analysis
│
├── visualization/ # Visualization
│ ├── charts.py # Chart generation
│ └── signal_maps.py # Signal heatmaps
│
├── backtesting/ # Backtesting module
│ ├── strategy.py # Strategy definition
│ └── evaluator.py # Backtesting evaluation
│
├── reporting/ # Report generation
│ ├── html_generator.py # HTML report
│ └── pdf_exporter.py # PDF export
│
├── utils/ # Utility functions
│ └── helpers.py # Helper functions
│
└── database/ # Database
├── manager.py # Database management
└── models.py # Data models
```
---
## Features
| Category | Description |
|----------|-------------|
| **Real-time Data** | Tushare 1 min / Tick data, automatic main contract mapping; yfinance GC & XAU/USD synchronized fetching |
| **MCP Factors** | 10+ indicators including MACD, VWAP, active buy/sell ratio, market depth, position Δ, etc. |
| **Signal Maps** | Multi-factor heatmaps, supports clicking to view trigger logic |
| **Strategy Backtesting** | Vectorized intraday backtesting, parameter scanning, profit/loss/drawdown curves |
| **Report Export** | One-click generation of HTML/PDF with charts |
| **MCP Server** | Provides utility functions like `get_gold_k_data`, `get_oi_delta`, `get_mcp_signal`, etc. |
---
## Prerequisites
1. **Python 3.10+**
2. **Dependency Management**: Recommended `uv`, also supports `pip`, `poetry`
3. **API Key**
* Tushare `TUSHARE_TOKEN`
* Alpha Vantage `ALPHAVANTAGE_KEY` (optional, for fetching XAU/USD)
4. **PostgreSQL Database**: Used for storing market data and analysis results
---
## Data Update Time
> *Shanghai Gold Tick/minute data is pushed by the exchange after trading hours at approximately 17:15, and completed by 02:45 the next day for night trading;
> International gold prices are updated in real-time via yfinance*.
- **Daily / Minute Data** is completed around 17:30 on the trading day
- **Night Trading Data** is completed around 03:00 the next day
- **Tick-level** fetching scripts write data to the local database in real-time
---
## Installation Environment
```bash
# 1. Clone the repository
git clone https://github.com/your-username/shfe-gold-mcp.git
cd shfe-gold-mcp
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure keys (environment variables)
export TUSHARE_TOKEN="your_token_here"
export ALPHAVANTAGE_KEY="your_key_here"
# 4. Create PostgreSQL database
# Configure database connection (set DATABASE_URL in environment variables)
```
---
## Usage
### Start the Streamlit Application
```bash
streamlit run app.py
```
The browser will automatically open to access: `http://localhost:8501`
### Application Features
1. **Data Analysis**: Load and display AU, COMEX GC, and XAU/USD data
2. **Technical Indicators**: Calculate and display various technical indicators (VWAP, MACD, RSI, etc.)
3. **Signal Maps**: Generate correlation and technical indicator signal maps
4. **Strategy Backtesting**: Test mean reversion, trend following, breakout, and arbitrage strategies
5. **Report Export**: Generate HTML and PDF reports
---
## Tool List
| Category | Tool | Description |
|----------|------|-------------|
| Market Data | `fetch_au_data` | AU main contract 1min / Tick K line |
| Market Data | `fetch_comex_gc` | COMEX GC continuous contract |
| Market Data | `fetch_xau_usd` | XAU/USD spot |
| Indicator Calculation | `add_macd` | Fast/slow lines & histogram |
| Indicator Calculation | `add_vwap` | Volume-weighted average price |
| Behavior Signals | `create_strategy` | Create strategy signals |
| Behavior Signals | `create_technical_signal_map` | Return heatmap matrix |
| Reporting | `generate_html_report` | Generate HTML report |
---
## Contribution Guidelines
- Issue Submission: Please include reproducible steps / sample dates
- PR: Must pass code quality checks
- Code Style: PEP‑8
---
## License
This project is licensed under the MIT License.
