<div align="center">

🚀 QuantConnect MCP Server

Professional-grade Model Context Protocol server for QuantConnect's algorithmic trading platform

Seamlessly integrate QuantConnect's research environment, statistical analysis, and portfolio optimization into your AI workflows

🎯 Quick Start • 📖 Documentation • 🏗️ Architecture • 🤝 Contributing

</div>

---

✨ Why QuantConnect MCP Server?

Transform your algorithmic trading research with a production-ready MCP server that provides:

• 🧪 Research Environment: Full QuantBook integration for interactive financial analysis
• 📊 Advanced Analytics: PCA, cointegration testing, mean reversion analysis, and correlation studies
• 🎯 Portfolio Optimization: Sophisticated sparse optimization with Huber Downward Risk minimization
• 🌐 Universe Selection: ETF constituent analysis and multi-criteria asset screening
• 🔐 Enterprise Security: SHA-256 authenticated API integration with QuantConnect
• ⚡ High Performance: Async-first design with concurrent data processing

📋 Table of Contents

• 🎯 Quick Start
• 🛠️ Installation
• 🔑 Authentication
• 🚀 Usage Examples
• 📖 Comprehensive API Reference
• 🏗️ Architecture
• 🔧 Advanced Configuration
• 🧪 Testing
• 🤝 Contributing
• 📄 License

🎯 Quick Start

Get up and running in under 3 minutes:

1. Install Dependencies

# Clone the repository
git clone https://github.com/your-org/quantconnect-mcp
cd quantconnect-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

2. Set Up QuantConnect Credentials

export QUANTCONNECT_USER_ID="your_user_id"
export QUANTCONNECT_API_TOKEN="your_api_token"
export QUANTCONNECT_ORGANIZATION_ID="your_org_id"  # Optional

3. Launch the Server

# STDIO transport (default)
python main.py

# HTTP transport
MCP_TRANSPORT=streamable-http MCP_PORT=8000 python main.py

4. Start Analyzing

# Initialize research environment
await initialize_quantbook(instance_name="research")

# Add securities for analysis
await add_multiple_equities(["AAPL", "MSFT", "GOOGL", "AMZN"], resolution="Daily")

# Perform sophisticated analysis
await perform_pca_analysis(
    symbols=["AAPL", "MSFT", "GOOGL", "AMZN"],
    start_date="2023-01-01",
    end_date="2024-01-01"
)

🛠️ Installation

Prerequisites

• Python 3.12+ (Type-annotated for maximum reliability)
• QuantConnect LEAN (Installation Guide)
• Active QuantConnect Account with API access

Standard Installation

# Using uv (fastest)
uv sync

# Using pip
pip install -e .

# Development installation with testing tools
uv sync --dev

Verify Installation

# Check server health
python -c "from src.server import mcp; print('✅ Installation successful')"

# Run test suite
pytest tests/ -v

🔑 Authentication

Getting Your Credentials

Credential	Where to Find	Required
User ID	Email received when signing up	✅ Yes
API Token	QuantConnect Settings	✅ Yes
Organization ID	Organization URL: /organization/{ID}	⚪ Optional

Configuration Methods

Method 1: Environment Variables (Recommended)

# Add to your .bashrc, .zshrc, or .env file
export QUANTCONNECT_USER_ID="123456"
export QUANTCONNECT_API_TOKEN="your_secure_token_here"
export QUANTCONNECT_ORGANIZATION_ID="your_org_id"  # Optional

Method 2: Runtime Configuration

# Configure programmatically
await configure_quantconnect_auth(
    user_id="123456",
    api_token="your_secure_token_here",
    organization_id="your_org_id"  # Optional
)

# Validate configuration
result = await validate_quantconnect_auth()
print(f"Auth Status: {result['authenticated']}")

Method 3: Interactive Setup

# Check current status
status = await get_auth_status()

# Test API connectivity
test_result = await test_quantconnect_api()

🚀 Usage Examples

Financial Research Pipeline

# 1. Initialize research environment
await initialize_quantbook(instance_name="research_2024")

# 2. Build universe from ETF constituents
await add_etf_universe_securities(
    etf_ticker="QQQ",
    date="2024-01-01",
    resolution="Daily"
)

# 3. Perform correlation analysis
correlation_matrix = await calculate_correlation_matrix(
    symbols=["AAPL", "MSFT", "GOOGL", "AMZN", "TSLA"],
    start_date="2023-01-01",
    end_date="2024-01-01"
)

# 4. Find uncorrelated assets for diversification
uncorrelated = await select_uncorrelated_assets(
    symbols=correlation_matrix["symbols"],
    num_assets=5,
    method="lowest_correlation",
    start_date="2023-01-01",
    end_date="2024-01-01"
)

# 5. Optimize portfolio with advanced algorithm
optimized_portfolio = await sparse_optimization(
    portfolio_symbols=uncorrelated["selected_assets"]["symbols"],
    benchmark_symbol="SPY",
    start_date="2023-01-01",
    end_date="2024-01-01",
    max_weight=0.15,
    lambda_param=0.01
)

Statistical Analysis Workflow

# Cointegration analysis for pairs trading
cointegration_result = await test_cointegration(
    symbol1="KO",
    symbol2="PEP",
    start_date="2023-01-01",
    end_date="2024-01-01",
    trend="c"
)

if cointegration_result["is_cointegrated"]:
    print(f"✅ Cointegration detected (p-value: {cointegration_result['cointegration_pvalue']:.4f})")
    
    # Analyze mean reversion opportunities
    mean_reversion = await analyze_mean_reversion(
        symbols=["KO", "PEP"],
        start_date="2023-01-01",
        end_date="2024-01-01",
        lookback_period=20
    )

Project and Backtest Management

# Create new algorithmic trading project
project = await create_project(
    name="Mean_Reversion_Strategy_v2",
    language="Py"
)

# Upload algorithm code
await create_file(
    project_id=project["project"]["projectId"],
    name="main.py",
    content=algorithm_code
)

# Run backtest
backtest = await create_backtest(
    project_id=project["project"]["projectId"],
    compile_id="latest",
    backtest_name="Mean_Reversion_Test_Run",
    parameters={"lookback_period": 20, "threshold": 2.0}
)

# Analyze results
results = await read_backtest(
    project_id=project["project"]["projectId"],
    backtest_id=backtest["backtest"]["backtestId"]
)

📖 Comprehensive API Reference

🔐 Authentication Tools

Tool	Description	Key Parameters
configure_quantconnect_auth	Set up API credentials	user_id, api_token, organization_id
validate_quantconnect_auth	Test credential validity	-
get_auth_status	Check authentication status	-
test_quantconnect_api	Test API connectivity	endpoint, method
clear_quantconnect_auth	Clear stored credentials	-

📊 Project Management Tools

Tool	Description	Key Parameters
create_project	Create new QuantConnect project	name, language, organization_id
read_project	Get project details or list all	project_id (optional)
update_project	Update project name/description	project_id, name, description

📁 File Management Tools

Tool	Description	Key Parameters
create_file	Create file in project	project_id, name, content
read_file	Read file(s) from project	project_id, name (optional)
update_file_content	Update file content	project_id, name, content
update_file_name	Rename file in project	project_id, old_file_name, new_name

🧪 QuantBook Research Tools

Tool	Description	Key Parameters
initialize_quantbook	Create new research instance	instance_name, organization_id, token
list_quantbook_instances	View all active instances	-
get_quantbook_info	Get instance details	instance_name
remove_quantbook_instance	Clean up instance	instance_name

📈 Data Retrieval Tools

Tool	Description	Key Parameters
add_equity	Add single equity security	ticker, resolution, instance_name
add_multiple_equities	Add multiple securities	tickers, resolution, instance_name
get_history	Get historical price data	symbols, start_date, end_date, resolution
add_alternative_data	Subscribe to alt data	data_type, symbol, instance_name
get_alternative_data_history	Get alt data history	data_type, symbols, start_date, end_date

🔬 Statistical Analysis Tools

Tool	Description	Key Parameters
perform_pca_analysis	Principal Component Analysis	symbols, start_date, end_date, n_components
test_cointegration	Engle-Granger cointegration test	symbol1, symbol2, start_date, end_date
analyze_mean_reversion	Mean reversion analysis	symbols, start_date, end_date, lookback_period
calculate_correlation_matrix	Asset correlation analysis	symbols, start_date, end_date

💰 Portfolio Optimization Tools

Tool	Description	Key Parameters
sparse_optimization	Advanced sparse optimization	portfolio_symbols, benchmark_symbol, optimization params
calculate_portfolio_performance	Performance metrics	symbols, weights, start_date, end_date
optimize_equal_weight_portfolio	Equal-weight optimization	symbols, start_date, end_date, rebalance_frequency

🌐 Universe Selection Tools

Tool	Description	Key Parameters
get_etf_constituents	Get ETF holdings	etf_ticker, date, instance_name
add_etf_universe_securities	Add all ETF constituents	etf_ticker, date, resolution
select_uncorrelated_assets	Find uncorrelated assets	symbols, num_assets, method
screen_assets_by_criteria	Multi-criteria screening	symbols, min_return, max_volatility, etc.

🔥 Backtest Management Tools

Tool	Description	Key Parameters
create_backtest	Create new backtest	project_id, compile_id, backtest_name
read_backtest	Get backtest results	project_id, backtest_id, chart
read_backtest_chart	Get chart data	project_id, backtest_id, name
read_backtest_orders	Get order history	project_id, backtest_id, start, end
read_backtest_insights	Get insights data	project_id, backtest_id, start, end

🏗️ Architecture

quantconnect-mcp/
├── 🎛️  main.py                    # Server entry point & configuration
├── 📊  src/
│   ├── 🖥️  server.py              # FastMCP server core
│   ├── 🔧  tools/                 # Tool implementations
│   │   ├── 🔐  auth_tools.py      # Authentication management
│   │   ├── 📁  project_tools.py   # Project CRUD operations
│   │   ├── 📄  file_tools.py      # File management
│   │   ├── 🧪  quantbook_tools.py # Research environment
│   │   ├── 📈  data_tools.py      # Data retrieval
│   │   ├── 🔬  analysis_tools.py  # Statistical analysis
│   │   ├── 💰  portfolio_tools.py # Portfolio optimization
│   │   ├── 🌐  universe_tools.py  # Universe selection
│   │   └── 📊  backtest_tools.py  # Backtest management
│   ├── 🔐  auth/                  # Authentication system
│   │   ├── __init__.py
│   │   └── quantconnect_auth.py   # Secure API authentication
│   └── 📊  resources/             # System resources
│       ├── __init__.py
│       └── system_resources.py   # Server monitoring
├── 🧪  tests/                     # Comprehensive test suite
│   ├── test_auth.py
│   ├── test_server.py
│   └── __init__.py
├── 📋  pyproject.toml             # Project configuration
└── 📖  README.md                  # This file

Core Design Principles

• 🏛️ Modular Architecture: Each tool category is cleanly separated for maintainability
• 🔒 Security First: SHA-256 authenticated API with secure credential management
• ⚡ Async Performance: Non-blocking operations for maximum throughput
• 🧪 Type Safety: Full type annotations with mypy verification
• 🔧 Extensible: Plugin-based architecture for easy feature additions

🔧 Advanced Configuration

Transport Options

# STDIO (default) - Best for MCP clients
python main.py

# HTTP Server - Best for web integrations
MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 python main.py

# Custom path for HTTP
MCP_PATH=/api/v1/mcp python main.py

Environment Variables

Variable	Description	Default	Example
MCP_TRANSPORT	Transport method	stdio	streamable-http
MCP_HOST	Server host	127.0.0.1	0.0.0.0
MCP_PORT	Server port	8000	3000
MCP_PATH	HTTP endpoint path	/mcp	/api/v1/mcp
LOG_LEVEL	Logging verbosity	INFO	DEBUG

System Resources

Monitor server performance and status:

# System information
system_info = await get_resource("resource://system/info")

# Server status and active instances  
server_status = await get_resource("resource://quantconnect/server/status")

# Available tools summary
tools_summary = await get_resource("resource://quantconnect/tools/summary")

# Performance metrics
performance = await get_resource("resource://quantconnect/performance/metrics")

# Top processes by CPU usage
top_processes = await get_resource("resource://system/processes/10")

🧪 Testing

Run the Test Suite

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test category
pytest tests/test_auth.py -v

# Run tests in parallel
pytest tests/ -n auto

Manual Testing

# Test authentication
python -c "
import asyncio
from src.auth import validate_authentication
print(asyncio.run(validate_authentication()))
"

# Test server startup
python main.py --help

🤝 Contributing

We welcome contributions! This project follows the highest Python development standards:

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/quantconnect-mcp
cd quantconnect-mcp

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install

Code Quality Standards

• ✅ Type Hints: All functions must have complete type annotations
• ✅ Documentation: Comprehensive docstrings for all public functions
• ✅ Testing: Minimum 90% test coverage required
• ✅ Formatting: Black code formatting enforced
• ✅ Linting: Ruff linting with zero warnings
• ✅ Type Checking: mypy verification required

Development Workflow

# Create feature branch
git checkout -b feature/amazing-new-feature

# Make changes and run quality checks
ruff check src/
black src/ tests/
mypy src/

# Run tests
pytest tests/ --cov=src

# Commit with conventional commits
git commit -m "feat: add amazing new feature"

# Push and create pull request
git push origin feature/amazing-new-feature

Pull Request Guidelines

1. 📝 Clear Description: Explain what and why, not just how
2. 🧪 Test Coverage: Include tests for all new functionality
3. 📖 Documentation: Update README and docstrings as needed
4. 🔍 Code Review: Address all review feedback
5. ✅ CI Passing: All automated checks must pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

<div align="center">

Built with ❤️ for the algorithmic trading community

⭐ Star this repo • 🐛 Report issues • 💡 Request features

</div>