MCP Hybrid Forecasting System
A professional-grade algorithmic trading system that combines advanced statistical models (ARIMA, ARIMA-GARCH) with machine learning (XGBoost) to generate stock trading signals with risk management and volatility analysis.
Features
Core Forecasting Models
- ARIMA Time Series Forecasting: Professional statistical models for trend prediction with parameter optimization
- ARIMA-GARCH Model: Volatility-aware forecasting for high-volatility and cryptocurrency stocks
- XGBoost Hybrid Model: Machine learning residual correction with 10+ technical indicators
- Hierarchical Ensemble Model: Advanced model combination for improved accuracy
Risk Management & Analysis
- Volatility Classification: Automatic detection of high-volatility stocks with configurable thresholds
- Confidence Scoring: Risk-managed buy/sell/hold decisions with confidence levels
- Portfolio Analysis: Multi-portfolio comparison and analysis capabilities
- Smart Caching: Intelligent result caching to avoid duplicate processing
MCP Server Integration
- MCP Protocol Support: Full Model Context Protocol server implementation
- Trading Tools: Analyze portfolios, compare strategies, find opportunities
- Market Summary: Real-time market analysis and signal generation
- Natural Language Queries: Find trading opportunities with intuitive queries
Production Features
- Comprehensive Error Handling: Robust error handling and logging
- Multi-Stock Support: Portfolio-level signal generation
- Configurable Portfolios: Pre-configured portfolios (tech, defensive, emerging tech, etc.)
- Flexible Output: CSV exports, charts, and detailed reports
Performance
- R² Accuracy: 0.71-0.96 across major stocks
- Feature Engineering: 10+ technical indicators including volume analysis, moving averages, momentum
- Signal Quality: Conservative risk-managed decisions with confidence scoring
- Cache Performance: 6-hour intelligent caching reduces redundant API calls
Quick Start
1. Installation
# Clone the repository
git clone <repository-url>
cd mcp-hybrid-forecasting
# Create virtual environment
python3 -m venv hybr_fcst_venv
source hybr_fcst_venv/bin/activate # On Windows: hybr_fcst_venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
2. Basic Usage
Run Standard Analysis
# Analyze default portfolio
python enhanced_main.py
# Analyze specific portfolio
python enhanced_main.py --portfolio tech_focus
# Analyze custom tickers
python enhanced_main.py --tickers AAPL MSFT GOOGL
# Filter by signal type
python enhanced_main.py --portfolio large_cap --signal BUY
Run with ARIMA-GARCH for High Volatility Stocks
# Use pure volatility detection
python enhanced_main.py --portfolio lenny_golub --mode volatility
# Use config-based crypto detection
python enhanced_main.py --portfolio custom --mode config
MCP Server Mode
# Start MCP server for Claude integration
python mcp_trading_server.py
3. Configuration
Edit config/trading_config.json to customize:
{
"tickers": {
"default": ["AAPL", "MSFT", "GOOGL", "AMZN"],
"tech_focus": ["AAPL", "MSFT", "GOOGL", "NVDA", "META"],
"defensive": ["PG", "KO", "PEP", "WMT", "TGT", "CVS"]
},
"trading_parameters": {
"buy_threshold": 0.02,
"sell_threshold": -0.02,
"confidence_threshold": 0.6
},
"risk_management": {
"max_volatility": 0.05,
"min_confidence": 0.6
}
}
Project Structure
mcp-hybrid-forecasting/
├── models/ # Forecasting models
│ ├── arima_model.py # ARIMA implementation with optimization
│ ├── arima_garch_model.py # ARIMA-GARCH for volatile stocks
│ ├── hybrid_model.py # XGBoost residual correction
│ └── hierarchical_ensemble_model.py # Ensemble modeling
├── config/ # Configuration files
│ ├── trading_config.json # Main trading configuration
│ └── extreme_volatility.json # Volatility classification
├── src/ # Source modules
│ ├── analysis/ # Analysis utilities
│ ├── data/ # Data fetching and processing
│ ├── trading/ # Trading logic
│ └── utils/ # Helper functions
├── cache/ # Model and data cache
├── results/ # Output results and reports
├── enhanced_main.py # Main trading system with dual model support
├── main.py # Core trading system
├── mcp_trading_server.py # MCP server implementation
└── requirements.txt # Python dependencies
Available Portfolios
The system includes pre-configured portfolios in config/trading_config.json:
- Technology:
default,tech_focus,emerging_tech,large_cap - Market Sectors:
financials,healthcare,energy,utilities,industrials - Investment Style:
growth,defensive,cyclical - Market Cap:
mega_cap,large_cap,mid_cap,small_cap - Crypto-Related:
lenny_golub(COIN, MSTR, HOOD, etc.) - Defense:
defence,defence1
Command Line Options
python enhanced_main.py --help
Options:
--portfolio PORTFOLIO Portfolio name from config (default: 'default')
--tickers TICKER [...] Custom list of tickers (overrides portfolio)
--signal SIGNAL Filter by signal: BUY, SELL, HOLD
--min-confidence FLOAT Minimum confidence threshold (0.0-1.0)
--mode MODE Volatility detection mode: 'config' or 'volatility'
--cache-hours HOURS Cache validity in hours (default: 6)
--output-dir DIR Output directory for results
MCP Server Tools
When running as an MCP server, the following tools are available:
- analyze_portfolio: Analyze specific portfolio with optional filtering
- compare_portfolios: Compare multiple portfolios with analysis
- find_opportunities: Natural language queries for trading opportunities
- get_market_summary: Overall market analysis and signal distribution
- refresh_data: Clear cache and refresh market data
Example queries:
- "Find high confidence buy opportunities"
- "Show defensive stocks with positive signals"
- "Compare tech_focus vs defensive portfolios"
Dependencies
Core Requirements
- Python 3.8+
- pandas >= 2.0.0
- numpy >= 1.24.0
- yfinance >= 0.2.18
Modeling
- scikit-learn >= 1.3.0
- xgboost >= 1.7.0
- statsmodels >= 0.14.0
- arch >= 5.0.0 (for GARCH models)
- pmdarima >= 2.0.4 (optional, for auto-ARIMA)
Visualization
- matplotlib >= 3.7.0
- seaborn >= 0.12.0
- plotly >= 5.17.0
Development
- pytest >= 7.4.0
- jupyter >= 1.0.0
- black >= 23.0.0
See requirements.txt for complete list.
Usage Examples
Example 1: Analyze Technology Stocks
python enhanced_main.py --portfolio tech_focus --signal BUY --min-confidence 0.7
Example 2: Compare Investment Strategies
python enhanced_main.py --portfolio growth
python enhanced_main.py --portfolio defensive
# Then compare results in results/ directory
Example 3: High Volatility / Crypto Stocks
# Analyze crypto-related stocks with ARIMA-GARCH
python enhanced_main.py --portfolio lenny_golub --mode volatility
Example 4: Custom Stock List
python enhanced_main.py --tickers AAPL MSFT GOOGL NVDA AMD --signal BUY
Output Files
Results are saved in the results/ directory:
- CSV files:
trading_signals_YYYYMMDD_HHMMSS.csv - Charts: Portfolio comparison charts (if enabled)
- Logs: Detailed execution logs with timestamps
Model Details
ARIMA Model
- Auto-optimization of (p,d,q) parameters
- Configurable order search space
- AIC-based model selection
- Handles non-stationary data with differencing
ARIMA-GARCH Model
- Volatility modeling for high-risk stocks
- Conditional heteroskedasticity handling
- Automatic fallback to ARIMA if GARCH fails
- Optimized for cryptocurrency and volatile tech stocks
XGBoost Hybrid
- Residual-based correction
- Technical indicators: RSI, MACD, Bollinger Bands
- Volume-weighted features
- Lag features and momentum indicators
Risk Management
The system implements multiple risk controls:
- Volatility filtering: Excludes extremely volatile stocks
- Confidence scoring: Only recommends high-confidence signals
- Threshold-based signals: Configurable buy/sell thresholds
- Position limits: Maximum position size constraints
Development
Running Tests
pytest tests/
Code Formatting
black .
flake8 .
Adding New Portfolios
Edit config/trading_config.json:
{
"tickers": {
"my_portfolio": ["TICK1", "TICK2", "TICK3"]
}
}
Troubleshooting
Common Issues
Import Errors
# Ensure virtual environment is activated
source hybr_fcst_venv/bin/activate
pip install -r requirements.txt
Data Fetch Failures
- Check internet connection
- Verify ticker symbols are valid
- yfinance API may have rate limits
ARIMA-GARCH Not Available
# Install arch library
pip install arch
Cache Issues
# Clear cache directory
rm -rf cache/*
Performance Tips
- Use caching: Default 6-hour cache reduces API calls
- Smaller portfolios: Analyze fewer stocks for faster results
- Adjust cache duration:
--cache-hoursparameter for your needs - Pre-optimize ARIMA: Use
preprocess_arima_params.pyfor parameter tuning
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
This project is for educational and research purposes. See LICENSE file for details.
Disclaimer
This software is for educational purposes only. It is not financial advice. Always do your own research and consult with a qualified financial advisor before making investment decisions. Past performance does not guarantee future results.
Acknowledgments
- Built with statsmodels, XGBoost, and yfinance
- MCP protocol by Anthropic
- Inspired by quantitative finance research and modern ML techniques
Contact
For questions, issues, or contributions, please open an issue on GitHub.
Version: 1.0.0 Last Updated: June 2025