[![QuantConnectMCP](/TheFractalyst/QuantConnectMCP/raw/main/assets/banner.svg)](https://github.com/TheFractalyst/QuantConnectMCP)

[![PyPI](https://img.shields.io/pypi/v/qc-lean-mcp?color=blue)](https://pypi.org/project/qc-lean-mcp/)
[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org/)
[![ChromaDB](https://img.shields.io/badge/ChromaDB-FF6F00)](https://trychroma.com/)
[![MCP](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/TheFractalyst/QuantConnectMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/TheFractalyst/QuantConnectMCP/actions/workflows/ci.yml)

Complete QuantConnect/Lean reference documentation MCP server with 1265 entries
covering 100% of the official QuantConnect v2 documentation sitemap.

[Quick Start](#quick-start) |
[Tools](#tools) |
[Configuration](#configuration) |
[Database](#database) |
[Development](#development)

---

## One Command. Two Minutes. Fully Functional.

```bash
pip install qc-lean-mcp
qc-lean-mcp
```

That's it. On first run, the server auto-builds the ChromaDB vector store from
shipped JSON data (takes 30-60 seconds for embedding model download + indexing).
Subsequent runs start instantly.

**What you get:**

- 6 MCP tools for QuantConnect/Lean docs lookup, code validation, and template generation
- 1265 entries indexed in a local ChromaDB vector store (100% offline)
- Sub-millisecond hot cache for priority lookups
- Python AST validation for Lean algorithms
- Common Python.NET issue detection and auto-repair
- Works with Claude Desktop, Cursor, Windsurf, OpenCode, and any MCP client

**What you need:**

- Python 3.10+
- Any MCP-compatible AI client

---

## Why QuantConnectMCP?

AI coding assistants hallucinate Lean API syntax. The QuantConnect API is large
(QCAlgorithm, Algorithm Framework, 200+ indicators, multiple asset classes) and
constantly evolving. Models trained on older code get method signatures wrong.

QuantConnectMCP gives AI assistants **authoritative, real-time access** to the
complete QuantConnect/Lean reference:

- **100% coverage**: 1257/1257 official QuantConnect v2 docs sitemap URLs
- **Semantic search**: Vector embeddings find relevant docs by meaning, not keywords
- **Code validation**: `qc_validate` checks Python Lean algorithms for common mistakes
- **Auto-repair**: `qc_repair` fixes Python.NET bridge issues, missing self. prefix, etc.
- **Code generation**: `qc_scaffold` generates validated algorithm templates
- **100% local**: No network calls at runtime (ChromaDB auto-builds from shipped data)

---

## Tools

```
+---------------------------+----------------------------------------------+
| Tool                      | Description                                  |
+---------------------------+----------------------------------------------+
| qc_lookup(name, kind?)    | Get complete docs for a symbol by exact name |
| qc_search(query, ...)     | Semantic search across all docs              |
| qc_browse(namespace, ...) | Enumerate all members of a namespace         |
| qc_validate(code?, ...)   | Validate Python syntax for Lean algorithms   |
| qc_repair(code, context)  | Fix common Python.NET issues in Lean code    |
| qc_scaffold(kind, name)   | Generate algorithm/indicator/research template|
+---------------------------+----------------------------------------------+
```

---

## Quick Start

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "qc-lean-mcp": {
      "command": "qc-lean-mcp"
    }
  }
}
```

### Cursor / Windsurf / OpenCode

```json
{
  "mcpServers": {
    "qc-lean-mcp": {
      "command": "qc-lean-mcp"
    }
  }
}
```

### SSE (HTTP)

```bash
qc-lean-mcp
# Then connect to http://localhost:8080
```

Or with environment variables:

```bash
TRANSPORT=sse PORT=8080 qc-lean-mcp
```

---

## Configuration

```
+-------------------------+---------------+--------------------------------+
| Env Var                 | Default       | Description                    |
+-------------------------+---------------+--------------------------------+
| TRANSPORT               | stdio         | Transport: stdio or sse        |
| PORT                    | 8080          | Port for SSE transport         |
| QC_DB_PATH              | ./qc_db       | ChromaDB path                  |
| QC_COLLECTION           | qc_reference  | ChromaDB collection name       |
| QC_EMBED_MODEL          | all-MiniLM-L6 | Sentence transformer model     |
| QC_MAX_RESULTS          | 100           | Max search results             |
| LOG_LEVEL               | INFO          | Logging level                  |
| LAZY_MODEL              | 0             | Skip model preload at startup  |
+-------------------------+---------------+--------------------------------+
```

---

## Database

- 1265 entries (QuantConnect v2 docs)
- 1257/1257 sitemap URLs (100% coverage)
- 20 namespaces: cloud, indicators, writing-algorithms, cli, docs, datasets,
  research, securities, reality-modeling, local, engine, ai, framework, etc.
- Hot cache for sub-millisecond priority lookups
- Auto-built on first run from shipped JSON data (14MB)

To rebuild the database:

```bash
qc-lean-mcp build
```

---

## Development

```
git clone https://github.com/TheFractalyst/QuantConnectMCP.git
cd QuantConnectMCP
pip install -e ".[dev]"
pytest tests/ -v
```

### Re-index ChromaDB

```bash
python pipeline/merge_and_index.py --reset
```

## Docker

```bash
docker build -t qc-lean-mcp .
docker run -p 8080:8080 -e TRANSPORT=sse qc-lean-mcp
```

## Tech Stack

- **FastMCP 3.0** - MCP server framework with FileSystemProvider auto-discovery
- **ChromaDB** - Local vector database for semantic search (cosine, 384-dim)
- **SentenceTransformers** - `all-MiniLM-L6-v2` embedding model
- **RapidFuzz** - Fuzzy string matching for name lookups
- **Loguru** - Structured logging

## Links

- [fractalyst.dev](https://fractalyst.dev/) - Portfolio
- [QuantConnect Documentation](https://www.quantconnect.com/docs/v2/) - Official docs
- [LEAN Engine](https://www.quantconnect.com/lean) - Open-source algorithmic engine
- [@TheFractalyst](https://x.com/TheFractalyst) - X / Twitter

## License

MIT - see [LICENSE](LICENSE)