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:

1. analyze_portfolio: Analyze specific portfolio with optional filtering
2. compare_portfolios: Compare multiple portfolios with analysis
3. find_opportunities: Natural language queries for trading opportunities
4. get_market_summary: Overall market analysis and signal distribution
5. 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

1. Use caching: Default 6-hour cache reduces API calls
2. Smaller portfolios: Analyze fewer stocks for faster results
3. Adjust cache duration: --cache-hours parameter for your needs
4. Pre-optimize ARIMA: Use preprocess_arima_params.py for parameter tuning

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. 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