https://github.com/taylorwilsdon/quantconnect-mcp
QuantConnect Algorithmic Trading Platform Orchestration MCP - Agentic LLM Driven Trading Strategy Design, Research & Implementation
https://github.com/taylorwilsdon/quantconnect-mcp
lean-engine quantconnect quantitative-finance stock-indicators trading trading-algorithms trading-platform
Last synced: 3 months ago
JSON representation
QuantConnect Algorithmic Trading Platform Orchestration MCP - Agentic LLM Driven Trading Strategy Design, Research & Implementation
- Host: GitHub
- URL: https://github.com/taylorwilsdon/quantconnect-mcp
- Owner: taylorwilsdon
- Created: 2025-06-10T00:10:54.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-19T20:40:31.000Z (4 months ago)
- Last Synced: 2025-06-19T21:19:17.082Z (4 months ago)
- Topics: lean-engine, quantconnect, quantitative-finance, stock-indicators, trading, trading-algorithms, trading-platform
- Language: Python
- Homepage: https://quantratic.com/mcp
- Size: 124 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 QuantConnect MCP Server
[](https://python.org)
[](https://github.com/fastmcp/fastmcp)
[](LICENSE)
[](https://github.com/psf/black)
[](https://mypy.readthedocs.io/)
**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](#-quick-start) •
[📖 Documentation](#-comprehensive-api-reference) •
[🏗️ Architecture](#-architecture) •
[🤝 Contributing](#-contributing)
---
## ✨ 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](#-quick-start)
- [🛠️ Installation](#️-installation)
- [🔑 Authentication](#-authentication)
- [🚀 Usage Examples](#-usage-examples)
- [📖 Comprehensive API Reference](#-comprehensive-api-reference)
- [🏗️ Architecture](#️-architecture)
- [🔧 Advanced Configuration](#-advanced-configuration)
- [🧪 Testing](#-testing)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
## 🎯 Quick Start
Get up and running in under 3 minutes:
### 1. **Install Dependencies**
```bash
# 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**
```bash
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**
```bash
# STDIO transport (default)
python main.py
# HTTP transport
MCP_TRANSPORT=streamable-http MCP_PORT=8000 python main.py
```
### 4. **Start Analyzing**
```python
# 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](https://www.quantconnect.com/docs/v2/lean-cli/installation/overview))
- **Active QuantConnect Account** with API access
### Standard Installation
```bash
# Using uv (fastest)
uv sync
# Using pip
pip install -e .
# Development installation with testing tools
uv sync --dev
```
### Verify Installation
```bash
# 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](https://www.quantconnect.com/settings/) | ✅ Yes |
| **Organization ID** | Organization URL: `/organization/{ID}` | ⚪ Optional |
### Configuration Methods
#### Method 1: Environment Variables (Recommended)
```bash
# 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
```python
# 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
```python
# Check current status
status = await get_auth_status()
# Test API connectivity
test_result = await test_quantconnect_api()
```
## 🚀 Usage Examples
### Financial Research Pipeline
```python
# 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
```python
# 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
```python
# 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
```bash
# 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:
```python
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](LICENSE) file for details.
---
**Built with ❤️ for the algorithmic trading community**
[](https://python.org)
[](https://github.com/fastmcp/fastmcp)
[](https://www.quantconnect.com)
[⭐ Star this repo](https://github.com/your-org/quantconnect-mcp) •
[🐛 Report issues](https://github.com/your-org/quantconnect-mcp/issues) •
[💡 Request features](https://github.com/your-org/quantconnect-mcp/discussions)