Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/duy0699cat/worldquant-brain-mcp

Python MCP server for automating WorldQuant BRAIN alpha-research workflows: async API client, batch-simulation lab, and an AST-based expression parser with novelty detection. Independent/unofficial project.
https://github.com/duy0699cat/worldquant-brain-mcp

async fastapi llm-agents mcp model-context-protocol python quantitative-finance worldquant

Last synced: 10 days ago
JSON representation

Python MCP server for automating WorldQuant BRAIN alpha-research workflows: async API client, batch-simulation lab, and an AST-based expression parser with novelty detection. Independent/unofficial project.

Awesome Lists containing this project

README 

          
# WorldQuant MCP



A Python [MCP](https://modelcontextprotocol.io) server for automating WorldQuant BRAIN

alpha-research workflows, plus a local reference pipeline that converts documentation

into LLM-friendly artifacts. Built as a personal research-engineering project.



> **Note:** This is an independent, unofficial project and is not affiliated with or

> endorsed by WorldQuant. WorldQuant's platform documentation is **not** included in this

> repository — you supply your own PDF (see *Reference ingestion*). Use of the BRAIN API is

> subject to WorldQuant's own terms.



## Status



Initial working scaffold in place.



Current capabilities:



- Load credentials from `.env` or `WQ_BRAIN_*` environment variables.

- Convert scanned or text-based PDFs into markdown and chunked JSON.

- Authenticate against `api.worldquantbrain.com`.

- Search local operator/reference material.

- Fetch platform operators, account details, and data fields.

- Turn text hypotheses into field proxies and expression templates.

- Ingest external research links or notes into mechanism summaries.

- Mutate seed expressions into nearby variants.

- Submit simulations and poll simulation progress.

- Simulate batches of expressions and rank the results.

- Fetch alpha details and submission status.

- Validate whether an alpha is ready to submit and summarize blockers.

- Compare candidate expressions against recent alphas and logged experiments.

- Persist local experiment memory for future agents.

- Submit alphas behind an explicit confirmation flag.



## Reference ingestion



The first implemented component is the PDF ingestion pipeline.



```powershell

.venv/Scripts/python.exe -m pip install -e .

wq-ingest-reference --input wq-ops.pdf

```



Generated artifacts (produced locally, git-ignored — not committed):



- `src/worldquant_mcp/reference/data/wq-ops.md`

- `src/worldquant_mcp/reference/data/wq-ops.chunks.json`



If the PDF has no text layer, the ingester falls back to OCR using in-process

Python libraries so it still works on a clean Windows machine.



## Running the MCP server



Install the package in editable mode:



```powershell

.venv/Scripts/python.exe -m pip install -e .

```



Do not start the stdio MCP server manually if you want to use it from VS Code. VS Code should launch it for you from `mcp.json`.



Add this to your user-level `mcp.json` or workspace `.vscode/mcp.json`:



```json

{

  "servers": {

    "worldquant-mcp": {

      "type": "stdio",

      "command": ".venv/Scripts/worldquant-mcp.exe",

      "env": {

        "WQ_BRAIN_EMAIL": "",

        "WQ_BRAIN_PASSWORD": ""

      }

    }

  }

}

```



After saving `mcp.json`, use the VS Code MCP server management UI to reload or start the server. Once it shows as running, the tools from this server become available to Copilot agents.



If you want to run the server yourself for debugging only, use one of these commands:



```powershell

.venv/Scripts/worldquant-mcp.exe

```



Or run it via Python:



```powershell

.venv/Scripts/python.exe -m worldquant_mcp

```



## Timeout behavior



- Polling tools now default to bounded waits instead of open-ended multi-minute blocking.

- `wait_simulation`, `batch_simulate`, and `parallel_mechanism_search` default to `180` seconds.

- Override with `timeout_seconds` when you intentionally want a longer or shorter wait.

- Set `WQ_BRAIN_MAX_POLL_SECONDS` if you want to change the client-wide default used by direct code paths.

- 429 handling is now more robust in the shared client: temporary rate limits are retried with bounded backoff, and `CONCURRENT_SIMULATION_LIMIT_EXCEEDED` backs off more aggressively before failing.

- Tune `WQ_BRAIN_RATE_LIMIT_MAX_RETRIES` and `WQ_BRAIN_RATE_LIMIT_MAX_WAIT_SECONDS` if you want stricter or looser retry behavior.



## Example session



Once the server is running, an MCP-aware agent calls the tools directly. Illustrative output

below (metric values are synthetic and field/alpha names are placeholders — no real platform

data is shown):



```text

> healthcheck

{ "status": "ok", "authenticated": true }



> get_platform_operators

[ "rank", "zscore", "ts_delta", "ts_backfill", "ts_decay_linear", "group_zscore", ... ]



> create_simulation  expression="rank()"  settings=USA/TOP3000/delay=1

{ "status": "COMPLETE", "alpha_id": "",

  "is": { "sharpe": 1.21, "fitness": 0.74, "returns": 0.052, "turnover": 0.11 } }



> validate_alpha_submission_by_id  alpha_id=""

{ "ready": false, "blocking": ["LOW_FITNESS"], "pending": ["SELF_CORRELATION"] }

```



The operator names above are part of BRAIN's public expression language; the pipeline never

hard-codes proprietary data fields or alpha identifiers.



## Implemented tools



- `healthcheck`

- `get_account`

- `get_platform_operators`

- `search_local_reference`

- `get_reference_operators`

- `get_data_fields`

- `get_recent_alphas`

- `get_alpha`

- `get_alpha_submission`

- `create_simulation`

- `batch_simulate`

- `summarize_alpha_batch_by_id`

- `mutate_alpha_expression`

- `map_research_hypothesis`

- `ingest_research_material`

- `get_simulation`

- `wait_simulation`

- `analyze_alpha_novelty`

- `log_alpha_experiment`

- `list_alpha_experiments`

- `validate_alpha_submission_by_id`

- `submit_alpha_by_id`



## Research Notes



- `docs/mcp-roadmap.md` tracks pragmatic MCP upgrades for alpha research.

- `docs/quant-journey.md` is a running experiment log for future agents.

- `src/worldquant_mcp/data/experiment_memory.json` stores the same experiments in machine-readable form.