# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-duy0699cat-worldquant-brain-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [duy0699cat](https://agentstack.voostack.com/s/duy0699cat)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [duy0699cat](https://github.com/duy0699cat)
- **Source:** https://github.com/duy0699cat/worldquant-brain-mcp

## Install

```sh
agentstack add mcp-duy0699cat-worldquant-brain-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [duy0699cat](https://github.com/duy0699cat)
- **Source:** [duy0699cat/worldquant-brain-mcp](https://github.com/duy0699cat/worldquant-brain-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-duy0699cat-worldquant-brain-mcp
- Seller: https://agentstack.voostack.com/s/duy0699cat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.