Lets an AI client install, update, and query local China A-share daily datasets for financial analysis.
Also known as randyy179/qlib-sync, qlib-sync
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 351
- Latest version
- 0.2.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is qlib-sync MCP?
qlib-sync lets an AI client install, update, and query local China A-share daily datasets for financial analysis.
Summary generated from the project's README
About qlib-sync MCP server
Financial analysts and developers working with China A-share datasets can use qlib-sync to manage and query local Qlib data through an AI assistant. The server automates the installation and updating of daily community releases from the investment_data repository, ensuring the local files are verified and consistent. It handles complex tasks like checksum verification, interrupted download resumes, and safe data swaps with automatic rollbacks if an update fails.
Running locally on macOS or Linux, the server connects to AI clients like Claude Desktop, Cursor, or Claude Code using the Model Context Protocol. Users set it up via the uvx command with the qlib-sync mcp argument. Once connected, the AI can use specific tools such as cn_get_prices to fetch daily bars for up to 20 symbols or cn_list_pool to identify members of the csi300 or csi500 indices. This setup keeps all financial data on your machine, ensuring privacy while providing the assistant with up-to-date market information.
What you can do with it
- 1Check data freshnessAsk the AI to verify if your local China A-share dataset is current or if an update is available.
- 2Retrieve historical stock pricesRequest daily closing prices for specific symbols like Moutai over a recent time period.
Written from the project's README. Every use case is checked against a quote from it.
How to install qlib-sync MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall qlib-sync MCP in Claude Code
$ claude mcp add qlib-sync -- uvx qlib-syncInstall qlib-sync MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"qlib-sync": {
"command": "uvx",
"args": [
"qlib-sync"
]
}
}
}Install qlib-sync MCP in VS Code
.vscode/mcp.json
{
"servers": {
"qlib-sync": {
"type": "stdio",
"command": "uvx",
"args": [
"qlib-sync"
]
}
}
}Install qlib-sync MCP in VS Code CLI
$ code --add-mcp '{"name":"qlib-sync","type":"stdio","command":"uvx","args":["qlib-sync"]}'Install qlib-sync MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"qlib-sync": {
"command": "uvx",
"args": [
"qlib-sync"
]
}
}
}Install qlib-sync MCP in Codex
$ codex mcp add qlib-sync -- uvx qlib-syncInstall qlib-sync MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.qlib-sync] command = "uvx" args = ["qlib-sync"]
Install qlib-sync MCP in Gemini CLI
$ gemini mcp add -s user qlib-sync uvx -- qlib-syncInstall qlib-sync MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"qlib-sync": {
"command": "uvx",
"args": [
"qlib-sync"
]
}
}
}Configuration
QLIB_SYNC_DATA_DIRDataset folder; defaults to ~/.qlib/qlib_data/cn_data
QLIB_SYNC_MIRROROptional prefix-style GitHub proxy for slow connections, e.g. https://ghfast.top
| Name | Description | |
|---|---|---|
| QLIB_SYNC_DATA_DIR | Dataset folder; defaults to ~/.qlib/qlib_data/cn_data | |
| QLIB_SYNC_MIRROR | Optional prefix-style GitHub proxy for slow connections, e.g. https://ghfast.top |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablerandyy179/qlib-sync is public and reachablegithub.com/randyy179/qlib-sync ↗Pass
- Package names this repository as its sourceqlib-sync names randyy179/qlib-sync as sourcepypi.org/project/qlib-sync/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for qlib-syncpypi.org/project/qlib-sync/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/randyy179/qlib-sync ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from qlib-syncPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubqlib-sync
Website: randyy179.github.io/qlib-sync
One command to install and keep current a local Qlib China A-share dataset, and an MCP server so AI assistants can read it.
pip install qlib-sync
qlib-sync cn update
Or without installing anything first: uvx --python 3.12 qlib-sync cn update.
(--python 3.12 because pyqlib publishes wheels up to Python 3.12; uv fetches that Python
for you if needed. With pip, use Python 3.10 to 3.12.)

That installs the daily community release from
chenditc/investment_data into
~/.qlib/qlib_data/cn_data, the location Qlib reads by default. Run the same command again
any time; when the data is already current it finishes in about a second.
Why not just wget and tar?
Qlib's README points A-share users to the community release with a wget and tar one-liner.
That works until it doesn't:
- An interrupted or truncated download extracts into a half-written dataset, or fails after the old one has already been overwritten.
- Upstream republishes releases. In November 2026 a data error was found and corrected (investment_data#163) and releases were republished under the same date. A date check alone never sees the fix.
- Every check downloads 550 MB, even when nothing changed.
The investment_data README itself describes a careful manual process: download the release
manifest, check the archive with qlib/validate_archive.py --require-publishable, then
extract. qlib-sync runs that validator itself, on every update: an unmodified copy (from
commit 68fdc66,
Apache-2.0) checks the manifest before the download and the archive after it. A test suite
feeds the same malformed releases to the upstream script and to qlib-sync and requires the same
verdict, and a weekly job flags any change upstream makes to the validator.
On top of that, qlib-sync skips the download when nothing changed, pins the manifest and the archive to one release tag, extracts beside the live data and swaps it in with rollback (rather than extracting on top of the existing folder), and picks up republished releases.
qlib-sync treats the dataset like a production system:
| Step | What happens |
|---|---|
| Check | Pins the latest release by tag and reads its 500-byte manifest. Already current: done, nothing downloaded. |
| Download | Resumes interrupted downloads; shows progress; optional mirror for slow links to GitHub. |
| Verify | investment_data's own validate_archive.py --require-publishable, unmodified: manifest fields and formats, size and sha256, every required calendar and index pool, date formats, ordering, and the future calendar. Anything it rejects is refused. |
| Stage | Extracts next to the active dataset; refuses downgrades. |
| Swap | Renames the new dataset into place, then runs a real Qlib read. |
| Roll back | Any failure after the swap moves the previous dataset back. |
| Report | New trading days, newly listed and delisted symbols. |
Verification is required by default. If the manifest is missing, unreadable, or rejected by
the validator, the update stops and your data stays as it was. --allow-unverified installs
anyway when the manifest cannot be verified, and the result and install record are then marked
unverified; a package whose checksum disagrees with a valid manifest is always refused.
The checks catch broken, truncated, tampered, or malformed packages. They cannot catch wrong
values inside a correctly published release (like the one in #163); for that, keep a rollback
copy with --keep-backup.
Commands
qlib-sync status # every local Qlib dataset at a glance
qlib-sync cn status # local date, pools, and whether a newer release exists
qlib-sync cn update # install or update (add --json for machine-readable output)
qlib-sync cn health-check # structure checks plus a real Qlib read
qlib-sync cn restore --list # rollback backups; restore --yes switches back
Useful options for cn update:
| Option | Effect |
|---|---|
--data-dir PATH |
Install somewhere other than ~/.qlib/qlib_data/cn_data |
--mirror URL |
Download through a prefix-style GitHub proxy such as https://ghfast.top (or set QLIB_SYNC_MIRROR) |
--keep-backup |
Keep the previous dataset for one rollback |
--protect FILE |
Carry a custom stock pool in instruments/ across updates (repeatable) |
--force |
Reinstall even when the dates match |
--allow-unverified |
Install when the manifest cannot be verified (marked unverified; checksum mismatches are still refused) |
The update replaces the whole cn_data folder. Anything you added there is lost unless you
pass it with --protect.
Mirrors
From mainland China, GitHub downloads can be slow or fail. Pass a mirror and qlib-sync downloads the package through it while still reading the manifest from GitHub directly when it can, so the checksum does not depend on the mirror. Mirrors are third-party services; qlib-sync does not endorse any of them.
Python
from qlib_sync import update_cn, status_cn, health_check_cn
result = update_cn() # raises qlib_sync.UpdateError on failure; data unchanged
print("\n".join(result.summary_lines()))
print(result.new_trading_days, result.added_symbols)
Use it from your AI assistant
qlib-sync includes an MCP server, the open standard most AI
tools use to call local tools. Any MCP client that can start a local command works, whichever
model it runs: Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, or a local model. The server
runs on your machine and reads the dataset there; there is no service to host and nothing
leaves your computer. It is listed in the MCP Registry
as io.github.randyy179/qlib-sync.
Every client needs the same two things: the command uvx and the arguments qlib-sync mcp.
| Client | How to add qlib-sync |
|---|---|
| Claude Desktop | Download qlib-sync.mcpb from the latest release and open it |
| Claude Code | claude mcp add qlib-sync -- uvx --python 3.12 qlib-sync mcp |
| OpenAI Codex CLI | codex mcp add qlib-sync -- uvx --python 3.12 qlib-sync mcp |
| Cursor | The JSON below, in ~/.cursor/mcp.json |
| Gemini CLI | The JSON below, in ~/.gemini/settings.json |
| Qwen Code | The JSON below, in ~/.qwen/settings.json |
| Tencent CodeBuddy, ByteDance Trae, Alibaba Tongyi Lingma | MCP settings, add a server manually, paste the JSON below |
| Cherry Studio | Settings, MCP servers, add: type STDIO, command uvx, arguments --python, 3.12, qlib-sync, mcp on separate lines |
| VS Code (Copilot agent mode) | .vscode/mcp.json: { "servers": { "qlib-sync": { "type": "stdio", "command": "uvx", "args": ["--python", "3.12", "qlib-sync", "mcp"] } } } |
{ "mcpServers": { "qlib-sync": { "command": "uvx", "args": ["--python", "3.12", "qlib-sync", "mcp"] } } }
Menu names and file locations change between versions; check your client's MCP documentation if a path above has moved. Tested with Claude Code and OpenAI Codex CLI.
Web chat apps such as ChatGPT connect only to remote MCP servers over the internet, so they cannot start this local server.
Set QLIB_SYNC_DATA_DIR to use a dataset outside ~/.qlib/qlib_data/cn_data, and
QLIB_SYNC_MIRROR to download through a mirror.
| Tool | Does |
|---|---|
cn_status |
Local latest date, pools, and whether an update is available |
cn_update |
Install or update (safe to call: failures restore the previous data) |
cn_health_check |
Structure checks plus a real Qlib read |
cn_get_prices |
Daily bars for up to 20 symbols; real traded prices by default, adjusted on request |
cn_list_pool |
Members of csi300, csi500, and other pools on a date |
Then ask things like "Is my A-share data current? What did Moutai close at over the last
week?" Symbols accept 600519, SH600519, or 600519.SH.

skills/qlib-sync/SKILL.md teaches an assistant when to update,
how to read each failure, and the price conventions. It uses the open SKILL.md format that
Claude, Codex, and other agents load from their skills folder; any assistant can also simply
be pointed at the file.
Daily updates
A run that finds nothing new costs one small request, so schedule it daily. See docs/scheduling.md for cron and launchd examples.
Data and credits
All data comes from chenditc/investment_data
(Apache-2.0). qlib-sync only downloads the public release; it does not host or redistribute
data. Prices follow Qlib's convention: $close is adjusted and the real price is
$close / $factor.
qlib-sync is an independent project, not affiliated with Microsoft or the Qlib team.
Supported: macOS and Linux, Python 3.10 to 3.12 (pyqlib does not publish wheels for newer
versions yet; uvx picks a compatible Python automatically).
Development
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest
License
MIT
qlib-sync MCP questions
How do I add qlib-sync MCP to Claude Code?
Run claude mcp add qlib-sync -- uvx qlib-sync in your terminal. Add --scope user to make it available in every project.
How do I add qlib-sync MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I update the dataset?
You can update the dataset using the command qlib-sync cn update or via an AI assistant using the provided MCP tools.
Is my data safe if an update fails?
Yes, the server uses a staging and swap process that includes a rollback mechanism to restore the previous dataset if any failure occurs.