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

[![PyPI](https://img.shields.io/pypi/v/mql-mcp?color=blue)](https://pypi.org/project/mql-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/MetatraderMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/TheFractalyst/MetatraderMCP/actions/workflows/ci.yml)

Complete MQL4/MQL5 reference documentation MCP server with 4853 entries
covering 100% of the official MetaTrader 4/5 documentation sitemaps.

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

---

## One Command. Two Minutes. Fully Functional.

```
pip install mql-mcp
mqlmcp
```

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 MQL4/MQL5 docs lookup, code validation, and code generation
* 4853 entries indexed in a local ChromaDB vector store (100% offline)
* Sub-millisecond hot cache for priority lookups
* MetaEditor compiler integration (local, Wine, or SSH) for `mql_compile`
* MQL4-to-MQL5 automatic migration via `mql_repair`
* Works with Claude Desktop, Cursor, Windsurf, OpenCode, and any MCP client

**What you need:**

* Python 3.10+
* Any MCP-compatible AI client

---

## Why MetaTraderMCP?

AI coding assistants hallucinate MQL syntax. MQL5 introduced significant changes
from MQL4 (handle-based indicators, CTrade class, CopyBuffer pattern, event model)
that models trained on older code get wrong.

MetaTraderMCP gives AI assistants **authoritative, real-time access** to the complete
MetaTrader 4/5 reference:

* **100% coverage**: 4136/4136 MQL5 + 657/657 MQL4 sitemap URLs
* **MQL4 + MQL5 unified**: Single database with version tagging and filtering
* **Semantic search**: Vector embeddings find relevant docs by meaning, not keywords
* **Real compilation**: `mql_compile` validates code via the actual MetaEditor compiler
* **MQL4 to MQL5 migration**: `mql_repair(mode="migrate")` applies all known replacements
* **Code generation**: `mql_scaffold` generates validated EA, indicator, or script templates
* **100% local**: No network calls at runtime (except optional compiler validation)

---

## Tools

```
+----------------------+---------------------------------------------+
| Tool                 | Description                                 |
+----------------------+---------------------------------------------+
| mql_lookup           | Get complete docs for a symbol by exact name|
| mql_search           | Semantic search across all MQL4/MQL5 docs   |
| mql_browse           | Enumerate all members of a namespace        |
| mql_compile          | Compile MQL code via MetaEditor or syntax   |
| mql_repair           | Fix compiler errors or migrate MQL4 to MQL5 |
| mql_scaffold         | Generate EA, indicator, or script template  |
+----------------------+---------------------------------------------+
```

### Tool Details

**`mql_lookup(name, kind?, version?)`**
Get complete documentation for an MQL symbol by exact name. Auto-detects function,
variable, type, constant, keyword, or operator. Returns syntax, parameters, returns,
remarks, and code examples. Filter by `version="mql4"` or `version="mql5"`.

**`mql_search(query, category?, namespace?, n_results?, version?)`**
Semantic search across the entire MQL4/MQL5 reference. Supports category filtering,
namespace filtering, and version filtering.

**`mql_browse(namespace, category?, style?, version?)`**
Enumerate every member of a namespace (e.g., `trade`, `indicator`, `array`).
`style="cheatsheet"` produces a compact, box-drawn signature summary.

**`mql_compile(code?, file_path?, explain?, version?)`**
Compile MQL code via the real MetaEditor compiler. Supports inline code, file paths,
and `explain=True` for error-specific fix hints. Compilation methods (tried in order):
local MetaEditor, remote SSH MetaEditor, syntax-only validation fallback.

**`mql_repair(code, context, mode?, version?)`**
Fix compiler errors (`mode="targeted"`) or migrate MQL4 code to MQL5
(`mode="migrate"`). Applies all known MQL4->MQL5 breaking change replacements,
then recompiles to verify.

**`mql_scaffold(kind, name, description?, version?, lots?, take_profit?, stop_loss?, magic_number?)`**
Generate a validated MQL EA, indicator, or script template. Pre-wired with standard
inputs, risk parameters, and trade logic. Result is compiled before return.

## MCP Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "metatradermcp": {
      "command": "mqlmcp",
      "transport": "stdio"
    }
  }
}
```

### Cursor / Windsurf / OpenCode

Add to your project's `.mcp.json` or global MCP config:

```json
{
  "mcpServers": {
    "metatradermcp": {
      "command": "mqlmcp",
      "transport": "stdio"
    }
  }
}
```

### SSE (HTTP)

```
TRANSPORT=sse PORT=8080 mqlmcp
```

Connect to `http://localhost:8080`.

## Configuration

```
+------------------------+---------------------+----------------------------------+
| Env Var                | Default             | Description                      |
+------------------------+---------------------+----------------------------------+
| TRANSPORT              | stdio               | Transport: stdio or sse          |
| PORT                   | 8080                | Port for SSE transport           |
| MQL_DB_PATH            | ./mql_db            | ChromaDB path                    |
| MQL_COLLECTION         | mql_reference       | ChromaDB collection name         |
| MQL_EMBED_MODEL        | all-MiniLM-L6-v2    | Sentence transformer model       |
| METAEDITOR_PATH        | (empty)             | Path to metaeditor64.exe         |
| METAEDITOR_SSH_HOST    | (empty)             | SSH host for remote compilation  |
| METAEDITOR_REMOTE_PATH | metaeditor64.exe    | Remote MetaEditor executable     |
| MQL_COMPILE_TIMEOUT    | 60                  | Compilation timeout in seconds   |
| LOG_LEVEL              | INFO                | Logging level                    |
| LAZY_MODEL             | 0                   | Set to 1 to defer model loading  |
+------------------------+---------------------+----------------------------------+
```

## Database

* 4853 entries (MQL4 + MQL5 unified)
* MQL5: 4136/4136 sitemap URLs (100%)
* MQL4: 657/657 sitemap URLs (100%)
* 37 documentation sections + 33 MetaTrader5 Python API pages
* Hot cache for sub-millisecond priority lookups
* Auto-built on first run from shipped JSON data (7.5MB)

To rebuild the database:

```
mqlmcp build
```

## Development

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

### Re-scrape from MQL Docs

```
pip install -e ".[pipeline]"
python -m playwright install chromium
python pipeline/scrape_mql5.py
python pipeline/scrape_mql4.py
python pipeline/merge_and_index.py --reset --output-json data/mql_merged_entries.json
```

## Docker

```bash
docker build -t metatradermcp .
docker run -p 8080:8080 -e TRANSPORT=sse metatradermcp
```

## Tech Stack

* **FastMCP 3.4** - 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 with daily rotation (SSE mode)

## Links

* [fractalyst.dev](https://fractalyst.dev/) - Portfolio
* [MQL5 Documentation](https://www.mql5.com/docs) - Official MQL5 reference
* [MetaTrader 5](https://www.metatrader5.com/) - Trading platform
* [@TheFractalyst](https://x.com/TheFractalyst) - X / Twitter

## License

MIT - see [LICENSE](LICENSE)
