Luogu MCP Server | ζ΄θ°· MCP Server
δΈζζζ‘£
A small MCP server for searching Luogu problems, reading statements and training sets, and finding related practice. It can run locally through npm or as a hosted Streamable HTTP server.
Quick Start
Use the hosted read-only server without installing anything:
{
"mcpServers": {
"luogu": {
"url": "https://luogu-mcp.ksrnyx.top/mcp"
}
}
}
To keep the server on your machine, use the published luogu-mcp-server package:
{
"mcpServers": {
"luogu": {
"command": "npx",
"args": ["-y", "luogu-mcp-server"]
}
}
}
Then ask:
Search Luogu for five beginner binary-tree problems.
Fetch Luogu P1305 with its statement and samples.
Find related practice for traversal-order confusion.
| Tool | Purpose |
|---|
luogu_search_problems | Search Luogu problems by keyword, topic, title fragment, problem id, and optional Luogu tag ids. |
luogu_fetch_problem | Fetch one Luogu problem statement, formats, samples, tags, difficulty, and URL by pid. |
luogu_resolve_problem | Resolve a Luogu URL, problem id, or title fragment, then fetch the problem. |
luogu_find_related_problems | Mix topic/pain-point recommendations with live keyword search to find related practice. |
luogu_list_algorithm_topics | List canonical algorithm topics, aliases, and known tag ids. |
luogu_find_topic_problems | Find topic practice problems using aliases, tag ids, deduplication, and match reasons. |
luogu_search_problem_sets | Search Luogu training/problem sets by keyword. Supports `type: "all" |
luogu_fetch_problem_set | Fetch one Luogu training/problem set and problem summaries by id. |
luogu_recommend_problems | Return seed recommendations from a topic or student pain point. |
luogu_get_user_profile | Fetch public Luogu user profile data by uid. |
luogu_get_capabilities | Report which LeetCode-style route features are available, auth-required, or planned. |
All tools are read-only.
Availability
- Hosted MCP:
https://luogu-mcp.ksrnyx.top/mcp
- Health:
https://luogu-mcp.ksrnyx.top/health
- Official MCP Registry:
io.github.Kaiserunix/luogu-mcp-server, described by server.json
Other Ways To Run
From source:
git clone https://github.com/kaiserunix/luogu-mcp-server.git
cd luogu-mcp-server
cmd /c npm install
cmd /c npm run build
Use node directly from a source checkout:
{
"mcpServers": {
"luogu": {
"command": "node",
"args": [
"C:\\path\\to\\luogu-mcp-server\\dist\\index.js"
],
"cwd": "C:\\path\\to\\luogu-mcp-server"
}
}
}
Example Calls
Search problems:
{
"keyword": "δΊεζ ",
"page": 1,
"limit": 5
}
Search problems with a Luogu tag filter:
{
"keyword": "δΊεζ ",
"tagIds": [11],
"limit": 5
}
Fetch a problem:
{
"pid": "P1305",
"maxStatementChars": 5000
}
Recommend from a pain point:
{
"topic": "binary_tree",
"painPoint": "traversal_order_confusion",
"limit": 3
}
Resolve a pasted URL:
{
"query": "https://www.luogu.com.cn/problem/P1305",
"maxStatementChars": 5000
}
Find related practice:
{
"topic": "binary_tree",
"painPoint": "traversal_order_confusion",
"query": "δΊεζ ιε",
"limit": 5
}
Find topic practice with alias expansion:
{
"topic": "Treap",
"limit": 5,
"excludeProblemIds": ["P3369"]
}
Fetch a public user profile:
Search training/problem sets:
{
"keyword": "η½η»ζ΅",
"type": "select",
"limit": 5
}
type: "all" is the default. It combines title-filtered official sets with selected user-shared set search. Use type: "official" for the public official index, or type: "select" for selected user-shared sets.
Luogu Route Parity
This project mirrors the useful shape of richer LeetCode MCP servers while respecting what Luogu exposes publicly:
- Available now: problem search, problem fetch, URL/id/title resolution, related problem discovery, training set search/fetch, public user profile fetch.
- Auth-required in live probes: recent submissions, public solution pages, and discussion pages.
- Planned but intentionally not enabled: solution submission/run-code tools. Those require authenticated session handling and explicit write-tool safety gates.
Development
cmd /c npm test
cmd /c npm run build
Cloudflare Worker Deployment
This package also includes a stateless Streamable HTTP MCP entrypoint for Cloudflare Workers.
cmd /c npm test
cmd /c npm run smoke:cf
cmd /c npx wrangler login
cmd /c npm run deploy:cf:dry
cmd /c npm run deploy:cf
The Worker exposes the same read-only tools at /mcp, with a health endpoint at / or /health.
{
"mcpServers": {
"luogu": {
"url": "https://<your-worker-name>.<your-workers-subdomain>.workers.dev/mcp"
}
}
}
Verify a deployed Worker:
cmd /c npm run smoke:cf -- https://<your-worker-name>.<your-workers-subdomain>.workers.dev
For private deployments, set LUOGU_MCP_TOKEN with wrangler secret put and configure your MCP client to send an Authorization: Bearer <token> header where supported. Browser Origin requests are rejected by default; set LUOGU_MCP_ALLOWED_ORIGINS to a comma-separated origin list if browser access is needed.
See docs/cloudflare-deployment.md for the full release checklist.
Run broad live checks against Luogu's current website responses:
cmd /c npm run smoke:live
The live smoke starts the MCP server through a real stdio client, then compares problem fetches, problem searches, training searches, training fetches, URL/id resolution, related recommendations, public user profiles, and route capabilities against Luogu content-only page responses. It is intentionally separate from unit tests because it depends on Luogu network availability and current site behavior.
Run the 100-topic algorithm coverage smoke:
cmd /c npm run smoke:topics
The topic smoke starts the real MCP server and probes 100 algorithm categories across high-level topic search and training-set search. It fails if fewer than 98 topic searches return Luogu results.
Download one representative problem per catalog topic into a local ignored folder:
cmd /c npm run download:topics
Test a MiMo agent loop that asks the model to choose MCP tools, then executes those calls through the local stdio MCP server:
cmd /c npm run smoke:mimo
smoke:mimo reads MIMO_API_KEY from the environment, or from C:\Users\qwerf\.continue\.env on this machine.
Notes
- Luogu endpoints used here are content-only web endpoints, not a formal stability contract.
- The server keeps outputs compact and structured for model context control.
- Browser automation is intentionally not the default path. A Playwright fallback can be added later for pages that cannot be read through lightweight HTTP.
- For broad topic discovery, Luogu training-set search is often cleaner than raw problem title search; raw keyword search follows Luogu's website ordering and can include title-level noise.