WorldQuant BRAIN (unofficial)

MCP server and LangGraph tools for WorldQuant BRAIN

[PyPI] [CI] [License: MIT]

mcp-server-worldquantbrain is a Model Context Protocol (MCP) server for the WorldQuant BRAIN API, with the same tools packaged for LangGraph and LangChain. It lets an agent look up data fields, backtest Fast Expression (FASTEXPR) alphas and read the results. Unofficial, and not affiliated with WorldQuant.

Why this exists

Driving BRAIN from an agent goes wrong in a few predictable ways, and each one shaped this package.

• A simulation takes minutes and clients give up sooner. A wait that runs out returns PENDING with an id, and get_simulation_status picks it up again. Nothing is resubmitted.
• Agents repeat themselves, and simulations are metered. A local ledger remembers every expression and settings pair, so a repeat returns the earlier alpha instead of spending quota.
• BRAIN responses are huge. Tools return trimmed, typed results: a PnL series becomes yearly figures, lists are paged and capped, and messages lose their embedded images.
• Logging in is awkward. The session is saved to disk, so restarts and short-lived stdio processes reuse it. If BRAIN asks for a biometric check you get a URL to open, not a headless browser you cannot see.
• Submission is permanent. submit_alpha does not exist unless you turn it on, and when it is on it runs BRAIN's checks and the self-correlation test first and refuses on any failure.

Quick start

Store your login once. Credentials go to ~/.config/mcp-server-worldquantbrain/credentials.json, readable only by you.

uvx mcp-server-worldquantbrain auth

Then add the server to your client.

Claude Code

claude mcp add brain -- uvx mcp-server-worldquantbrain

Claude Desktop, Cursor, VS Code and others

{  "mcpServers": {    "brain": { "command": "uvx", "args": ["mcp-server-worldquantbrain"] }  }}

Now ask for something like "Find a value signal in the fundamental datasets for USA TOP3000 and backtest it."

Prefer to pass credentials directly? Add "env": {"WQB_EMAIL": "...", "WQB_PASSWORD": "..."}.

LangGraph and LangChain

The langgraph extra gives you plain LangChain tools in the same process, with no MCP server to run. It also has a prebuilt agent.

uv add "mcp-server-worldquantbrain[langgraph]"

from mcp_server_worldquantbrain.integrations.langgraph import create_brain_agent, get_brain_tools
agent = create_brain_agent("anthropic:claude-sonnet-5")result = await agent.ainvoke({"messages": [("user", "Backtest rank(-returns) and summarize it")]})
# Or take the tools and build your own graph:tools = get_brain_tools()

The tools work from sync and async graphs. With WQB_ALLOW_SUBMIT=true the agent stops for human approval before submit_alpha. Invoke it with a thread_id in the config, and resume with Command(resume=...). get_brain_tools() leaves submit_alpha out, because a custom graph has no approval step; pass include_submit=True once yours does.

To keep BRAIN in a separate process, connect over MCP instead. This route needs langchain[mcp], which LangChain still marks as beta.

from langchain.agents import create_agentfrom langchain.mcp import MCPAdapter
config = {    "mcpServers": {        "brain": {            "command": "uvx",            "args": ["mcp-server-worldquantbrain"],            "timeout": 1_200_000,  # milliseconds; simulations block        }    }}
async with MCPAdapter(config) as adapter:    agent = create_agent("anthropic:claude-sonnet-5", await adapter.list_tools())

The subprocess inherits only HOME, PATH and a few others, so anything else, including WQB_* variables, has to go in env. Over this route a submission confirmation arrives as a LangGraph interrupt, so give the agent a checkpointer if you enable submission. A deployable example is in examples/langgraph_app.

draw_mermaid(agent) from mcp_server_worldquantbrain.integrations.langgraph returns the graph as a Mermaid flowchart, for the prebuilt agent or a graph of your own. Tools are grouped by area and colored by what they can change. This is the prebuilt agent with WQB_ALLOW_SUBMIT=true:

---config:  flowchart:    nodeSpacing: 24    rankSpacing: 12    padding: 8---flowchart TB    subgraph agent["Agent graph"]        direction LR        n0([start])        n1["model"]        n2["tools"]        n3{{"human approval<br/>before submit_alpha"}}:::approval        n4([end])        n3 -.-> n4        n3 -.->|"rejected"| n1        n3 -.->|"approved"| n2        n0 --> n1        n1 --> n3        n2 -.-> n1    end    subgraph tools["Tools"]        direction TB        subgraph tools_row0[" "]            direction LR            subgraph tools_auth["Login"]                direction LR                tools_auth_read["auth_status"]:::read                tools_auth_write["authenticate<br/>complete_authentication"]:::write            end            subgraph tools_simulations["Simulate"]                direction LR                tools_simulations_read["get_simulation_status<br/>get_simulation_options"]:::read                tools_simulations_write["simulate_alpha<br/>simulate_alphas_batch"]:::write            end            subgraph tools_submit["Submit"]                direction LR                tools_submit_irreversible["submit_alpha"]:::irreversible            end            tools_auth ~~~ tools_simulations ~~~ tools_submit        end        subgraph tools_row1[" "]            direction LR            subgraph tools_alphas["Alphas"]                direction LR                tools_alphas_read["get_alpha<br/>list_alphas<br/>get_alpha_pnl<br/>list_alpha_recordsets<br/>get_alpha_recordset<br/>check_alpha_submission<br/>get_alpha_self_correlation<br/>get_alpha_prod_correlation"]:::read                tools_alphas_write["update_alpha"]:::write            end            subgraph tools_data["Data"]                direction LR                tools_data_read["list_datasets<br/>get_dataset<br/>list_datafields<br/>get_datafield<br/>list_data_categories<br/>list_operators"]:::read            end            subgraph tools_users["Account"]                direction LR                tools_users_read["get_user_profile<br/>get_user_activity<br/>list_messages"]:::read            end            tools_alphas ~~~ tools_data ~~~ tools_users        end        tools_row0 ~~~ tools_row1    end    agent -- tool calls --> tools    subgraph legend["Legend"]        direction TB        legend_read["read-only"]:::read        legend_write["changes account state"]:::write        legend_irreversible["irreversible"]:::irreversible    end    brain["BRAIN API"]:::external    tools -- HTTPS --> brain    tools ~~~ legend    classDef default fill:#64748b,fill-opacity:0.06,stroke:#64748b    classDef read fill:#64748b,fill-opacity:0.14,stroke:#64748b    classDef write fill:#d97706,fill-opacity:0.16,stroke:#d97706    classDef irreversible,approval fill:#dc2626,fill-opacity:0.16,stroke:#dc2626,stroke-width:2px    classDef external fill-opacity:0,stroke-dasharray:5 4    classDef box fill:#64748b,fill-opacity:0.05,stroke:#64748b,stroke-opacity:0.45    classDef row fill:none,stroke:none    class agent,tools,tools_auth,tools_simulations,tools_submit,tools_alphas,tools_data,tools_users,legend box    class tools_row0,tools_row1 row

Tools

Resources: brain://operators, brain://simulation-options, brain://alphas/{alpha_id}, and reference pages under brain://docs/ (fastexpr-cheatsheet, settings-guide, submission-criteria).

Prompts: design_alpha runs a short research loop. review_alpha assesses an existing alpha.

Configuration

All settings are environment variables. A .env file in the working directory also works, except for settings that decide where credentials go or that enable submission (WQB_BASE_URL, the file and directory paths, the WQB_SUBMIT_* and WQB_ALLOW_SUBMIT settings, and the bearer token). These have to be set in the real environment.

On Windows the two directories are %APPDATA%\mcp-server-worldquantbrain and %LOCALAPPDATA%\mcp-server-worldquantbrain, and files are protected by your user profile rather than POSIX permissions.

To serve over HTTP:

WQB_HTTP_BEARER_TOKEN=change-me mcp-server-worldquantbrain serve --transport streamable-http --host 0.0.0.0

The server refuses a non-local address without a token. /health stays open for probes.

How it behaves

Long calls. Claude Desktop has been reported to cancel stdio tool calls after about a minute, so for that client each call is limited to 45 seconds of waiting and the agent resumes with get_simulation_status. Claude Code and LangGraph wait as long as you let them. Set WQB_SIMULATION_TIMEOUT to match whatever your client allows.

Concurrency. BRAIN limits simultaneous simulations per account and does not publish the number. The default of 2 is deliberately cautious. Raise it if your account allows more. The setting only counts blocking calls while they wait, and one batch group of up to 10 uses one slot. wait=False calls, simulations still running after a timeout, and other processes on the same account are not counted, and can hit BRAIN's own limit, which comes back as a rate-limit error with a suggested wait.

The ledger. Whitespace in an expression does not matter; every setting does. Pass force=True to run an identical simulation again. Failed simulations can be run again.

Writes are not retried. A POST that may have reached BRAIN is never repeated automatically, so a network failure cannot spend quota twice or submit twice. Reads retry with backoff and honour Retry-After.

Biometric login. authenticate returns a URL, the user finishes the check in a browser, and complete_authentication ends the login. The pending check is saved for 30 minutes, so it survives a restart. On a terminal, mcp-server-worldquantbrain auth does the same with a prompt.

What is cached. Operators and simulation options for a week, categories and dataset pages for a day. Alphas, simulations, checks, correlations and data fields are always fetched fresh.

What is never logged. Passwords, cookies, authorization headers and session tokens are masked, and email addresses are shortened, in logs and error messages.

Limitations

• BRAIN's API documentation sits behind a login, and BRAIN can change the API without notice. Run WQB_LIVE=1 uv run pytest -m live to check it against your account.
• Login, saved sessions, data catalogues, single simulations, alpha search, PnL, recordsets, submission checks and self-correlation have been run against a live account. Biometric completion, multi-simulation, update_alpha, submit_alpha and production correlation results have only been tested against responses documented by other BRAIN clients, so treat them as less proven. If a biometric completion fails, log in once on the BRAIN website and call authenticate with force=true.
• The self-correlation gate fails closed: if BRAIN will not report the figure, submit_alpha refuses. Set WQB_SUBMIT_CORRELATION_GATE=0 on accounts where that endpoint is unavailable.
• Simulations are REGULAR FASTEXPR alphas. SUPER and region-agnostic alphas, Python alphas, forum access, payments, competitions and pyramids are not covered.
• There is no cancel tool, because no cancel endpoint is known.
• credentials.json is plaintext protected by file permissions. Use WQB_EMAIL and WQB_PASSWORD from your own secret store if that is not enough.
• Check that your use of automation complies with the BRAIN terms that apply to you.

Other WorldQuant BRAIN projects

• cnhkmcp is on PyPI and covers far more of the platform, including the forum. It is a large install that bundles Selenium.
• lavender1203/world-quant-brain-mcp has the deepest local analytics, such as correlation pools and an alpha history database. It runs with Docker and Redis over HTTP, and has no license.
• QuantGPT is a full research agent with its own knowledge base, for when you want the loop rather than the tools.
• worldquant-harness adds local backtests and a strict human submission boundary.
• brainapi-go-sdk is a Go SDK and CLI with static binaries and tests built on captured API responses.
• rocky-d/wqb is a plain Python client, if you do not need an agent interface.

No code in this repository was copied from those projects.

Development

To point a client at a checkout, use uvx --from /path/to/mcp-server-worldquantbrain mcp-server-worldquantbrain, or uv add --editable ../mcp-server-worldquantbrain from your LangGraph project. See CONTRIBUTING.md and RELEASING.md.

License

MIT