qlib

You can run and interact with the qlib-mcp server to query data, analyze factors, and backtest strategies using a local Python-based MCP server. This setup lets you use your preferred MCP client to access Qlib’s data and analytics through a streamlined, programmable interface.

How to use

You connect your MCP client to the qlib-mcp server by registering the local Python process that runs the server code. Once registered, you can initialize the Qlib data environment, fetch historical data, perform factor analyses, and run TopK backtests directly from your MCP client.

How to install

Prerequisites You need Python 3.10 or newer (3.12 is recommended). Ensure Python is available on your system and accessible from your shell.

Install the required Python packages using pip.

pip install pyqlib mcp

Additional setup steps

Download Qlib data (A-share daily data ~500 MB) to enable data queries and backtesting.

python -m qlib.run.get_data qlib_data \
  --target_dir ~/.qlib/qlib_data/cn_data \
  --region cn

Register to an MCP client

To connect your MCP client, register the qlib MCP server with your client configuration using the following directive.

{
  "mcpServers": {
    "qlib": {
      "command": "python",
      "args": ["/path/to/qlib-mcp/server.py"],
      "description": "Microsoft Qlib MCP server"
    }
  }
}

Notes on the registration

Replace "/path/to/qlib-mcp/server.py" with the actual path to the server script on your system. For example, you might point to a specific Python installation and the server script location.

Usage flow overview

1. Initialize Qlib data environment with your chosen data path and region. 2) List instruments like CSI300 components to refine your universe. 3) Query historical prices and factor data with expressions. 4) Run factor analyses to validate factors. 5) Perform TopK backtests across your chosen market and time period.

Troubleshooting tips

If the client cannot reach the MCP server, verify that the Python process running server.py is active and that the path to server.py in the MCP client configuration is correct. Ensure your Python environment has the required packages installed and that any firewall or network restrictions allow local IPC if applicable.

Security considerations

Limit access to the MCP server to trusted clients. Use a secure development environment and avoid exposing the local server to unsecured networks. Maintain up-to-date Python and dependencies to reduce security risks.

Examples of common actions

Initialize Qlib data environment, then query data or run analyses using the MCP client as you would with any other MCP-enabled tool.

Available tools

qlib_init

Initialize the Qlib data environment; must be called first to set up data paths and region.

qlib_download_data

Download command to obtain A-share or US data sets for Qlib.

qlib_list_instruments

Query index component lists such as CSI300 or CSI500 constituents.

qlib_get_data

Query historical prices and factor data using Qlib expressions.

qlib_backtest_topk

Backtest TopK momentum strategies and return annualized metrics like return, Sharpe, and max drawdown.

qlib_factor_analysis

IC analysis and quantile-based returns to quickly validate factor effectiveness.

qlib_expression_help

Expression syntax help for operators and Alpha158 references.