mcp-server-codeforces
Provides read-only access to the official Codeforces API, enabling AI assistants to search problems, retrieve problem metadata, build practice ladders, inspect user profiles and rating history, analyze submissions and performance statistics, compare users, access leaderboards, and query contests, standings, rating changes, and recent submissions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-codeforces Find five 1200-1400 rated dp problems I can practice."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-codeforces
Docs & showcase: https://iamrudhresh.github.io/mcp-server-codeforces/
A read-only Model Context Protocol (MCP) server for the official Codeforces API. It gives AI assistants (Claude Desktop, Claude Code, Cursor, Cline, Gemini and others) structured, context-friendly JSON for problems, users, contests and performance analytics.
It ships in two interchangeable runtimes that expose the same 17 tools with the same output shapes:
Node.js (ESM) — zero-config
npxSTDIO server.Python (FastMCP) — STDIO or Streamable HTTP, Docker-ready.
Unofficial project, not affiliated with or endorsed by Codeforces. It never submits or runs code and never accepts Codeforces credentials.
Tools
Problemset
Tool | Description |
| Search by id ( |
| Name, rating, tags, solved count and canonical URL for one problem. |
| Practice ladder: most-solved problems carrying all given tags within a rating range. |
Users & analytics
Tool | Description |
| Profiles for 1–10 handles: rating, max rating, rank, tier, country, organization, contribution. |
| Rating history (newest first) with deltas, best rating, biggest gain and drop. |
| Recent submissions compacted to verdict / problem / language / time / memory. |
| Derived analytics: solved vs attempted, acceptance rate, verdicts, languages, top tags, solved-by-rating curve. |
| 2–5 handles side by side, highest rated first. |
| The rated leaderboard, optionally active-only or above a rating — always capped. |
Contests
Tool | Description |
| Contests filtered by phase ( |
| Next scheduled contests, soonest first, with hours until start. |
| Contest info, problem list and a window of ranked rows; filter by handles. |
| Old/new rating and delta per participant after a rated contest. |
| Submissions in a contest, optionally for one handle. |
| Live platform-wide submission feed. |
Meta
Tool | Description |
| Supported / degraded / unsupported operations (read-only contract). |
| Live probe plus layered health: transport, schema, auth, upstream. |
Argument naming: the Node runtime uses camelCase (problemId, minRating, contestId,
from, sampleSize); the Python runtime uses snake_case (problem_id, min_rating,
contest_id, from_rank / from_index, sample_size). Outputs are identical.
Related MCP server: mcp-codeforces
Quick start
Node.js (recommended)
npx -y mcp-server-codeforcesClaude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) or Cline:
{
"mcpServers": {
"codeforces": {
"command": "npx",
"args": ["-y", "mcp-server-codeforces"]
}
}
}Claude Code:
claude mcp add codeforces -- npx -y mcp-server-codeforcesPython
python -m venv venv
# Windows: .\venv\Scripts\activate Linux/macOS: source venv/bin/activate
pip install -r requirements.txt
python run_server.py # STDIO
python run_server.py --http --port 8000 # Streamable HTTP at http://localhost:8000/mcp{
"mcpServers": {
"codeforces": {
"command": "/absolute/path/venv/bin/python",
"args": ["/absolute/path/mcp-server-codeforces/run_server.py"]
}
}
}Docker (HTTP)
docker compose up --build # MCP endpoint: http://localhost:8000/mcpRemote clients then use { "url": "http://localhost:8000/mcp" }.
Example prompts
Find five 1200-1400 rated dp problems I can practice.
How has tourist's rating changed over his last 10 contests?
Compare Benq, jiangly and tourist.
When is the next Codeforces round?
Show the top 10 of contest 1700 and how my_handle placed.Design notes
English names. Codeforces returns Russian titles unless
lang=enis sent, so every request pinslang=en.Standings are fetched bare. For anonymous callers Codeforces only accepts
contest.standings?contestId=<id>and rejects any extra parameter. The server fetches the official table once, caches it, and appliesfrom/count/handleslocally.Rate limiting. Codeforces allows about one call every two seconds. All requests go through a single serialized throttle (1.1 s), a TTL cache, and exponential backoff on
Call limit exceeded, HTTP 429/403/5xx and timeouts.Context safety. Large payloads (the ~20 MB problemset, the 26 MB rated list, full standings) are normalized and always capped before they reach the model. Submissions are compacted to the fields an LLM needs.
Strict input validation. Handles must match
^[A-Za-z0-9._-]{3,24}$, so malformed input fails locally instead of spending a rate-limited request.Hardened transport. Responses redirected off
codeforces.comare refused; bodies are read with a 96 MB ceiling; errors carry stable codes (NOT_FOUND,INVALID_HANDLE,RATE_LIMITED,SCHEMA_CHANGED,NETWORK_TIMEOUT,UPSTREAM, …).Read-only by construction. No tool authenticates, executes code or submits solutions.
Project structure
mcp-server-codeforces/
├── src/ # Node.js runtime
│ ├── server.js # STDIO entrypoint (bin)
│ ├── tools.js # 17 tool registrations (zod schemas)
│ ├── api.js # Codeforces operations & analytics
│ ├── http.js # Throttle, cache, retries, envelope handling
│ ├── normalize.js # Pure normalizers and search scoring
│ └── errors.js # Error taxonomy
├── app/ # Python runtime (FastMCP)
│ ├── client/ # http.py, api.py, normalize.py (mirrors src/)
│ ├── tools/ # problems, users, contests, meta
│ ├── utils/ # logger (stderr only), errors
│ ├── config.py # Env-driven settings
│ ├── main.py # Streamable HTTP ASGI app
│ └── mcp_server.py # FastMCP instance
├── test/ # Node tests: unit, live smoke, MCP stdio
├── tests/ # Python tests: unit, mocked API, server/stdio, live
├── docs/index.html # GitHub Pages site
├── run_server.py # Python CLI (STDIO / --http)
├── Dockerfile, docker-compose.yml
└── server.json # MCP Registry metadataTesting
# Node
npm run test:unit # offline unit tests
npm run test:live # live smoke test against codeforces.com
npm run test:mcp # boots the stdio server and speaks MCP to it
npm test # all three
# Python
pytest # offline: unit, mocked API, MCP in-process + stdio end-to-end
CF_LIVE=1 pytest tests/test_live.py # live suite against codeforces.comCI runs the offline suites on Node 20/22/24 and Python 3.10/3.12/3.13.
Configuration (Python, optional)
See .env.example. Nothing is required; there are no credentials.
Variable | Default | Purpose |
|
| HTTP transport bind |
|
| Language for names |
|
| Seconds between upstream calls |
|
| Per-request timeout (s) |
|
| Retry attempts for transient failures |
|
| Cache lifetimes (s) |
Releasing
Bump
versioninpackage.json,server.json,src/server.jsandapp/__init__.py.Tag and push:
git tag v1.0.1 && git push --tags.The Publish workflow publishes to npm via trusted publishing (OIDC, no token).
License
MIT — see LICENSE. Codeforces data and trademarks belong to Codeforces.
Available Tools
17 toolscompare_usersCompare Codeforces usersARead-onlyIdempotent
Fetch compact side-by-side profiles for 2-5 handles sorted by rating. Handy for 'who is stronger' or team-selection questions.
Inputs: handles (required).
get_capabilitiesGet Codeforces provider capabilitiesARead-onlyIdempotent
Report which Codeforces operations this server supports, which are degraded, and which are deliberately unsupported (this adapter is strictly read-only and never submits code or accepts credentials). Call this first to discover the safe surface area.
Inputs: no named parameters.
get_contest_listList Codeforces contestsARead-onlyIdempotent
List Codeforces contests with start time, duration, type and phase. Filter by phase (BEFORE = upcoming, CODING = running, FINISHED = past) or switch to the gym archive.
Inputs: gym, limit, phase.
get_contest_rating_changesGet Codeforces contest rating changesARead-onlyIdempotent
Return the rating deltas applied after a rated contest: handle, rank, old rating, new rating and the computed change. Only available once the contest has been rated.
Inputs: contestId (required), limit.
get_contest_standingsGet Codeforces contest standingsARead-onlyIdempotent
Fetch the standings table for a contest: contest metadata, the problem list, and a bounded window of ranked rows with points, penalty, hacks and per-problem results. Pass 'handles' to look up specific competitors instead of the top of the table.
Inputs: contestId (required), from, count, handles, +1 more.
get_contest_statusGet Codeforces contest submissionsARead-onlyIdempotent
Return submissions made in a specific contest, optionally narrowed to a single handle. Useful for reviewing what a competitor submitted and which verdicts they received.
Inputs: contestId (required), from, count, handle.
get_healthGet Codeforces provider healthARead-onlyIdempotent
Probe the official Codeforces API and report transport, schema, auth and upstream health, plus the last observed error and request latency. Use this to diagnose failing tool calls.
Inputs: probe.
get_problem_metadataGet Codeforces problem metadataARead-onlyIdempotent
Fetch official metadata for one problem by id ('158A', '158/A' or '158-A'): name, rating, tags, solved count and canonical URL. Note: the Codeforces API does not expose the full problem statement, so this returns metadata only.
Inputs: problemId (required).
get_rated_usersGet Codeforces leaderboardARead-onlyIdempotent
Return the top rated Codeforces users, optionally only currently-active users or above a minimum rating. The upstream list has hundreds of thousands of entries, so results are always capped to protect context size.
Inputs: limit, minRating, activeOnly.
get_recent_submissionsGet recent Codeforces submissionsARead-onlyIdempotent
Return the most recent submissions across the whole Codeforces platform, compacted to verdict, problem, language and runtime. Useful for sampling live activity.
Inputs: count.
get_upcoming_contestsGet upcoming Codeforces contestsARead-onlyIdempotent
Return the next scheduled Codeforces contests, soonest first, including how many hours away each one starts. Use for 'when is the next contest' questions.
Inputs: limit.
get_user_infoGet Codeforces user profileARead-onlyIdempotent
Fetch structured profile data for 1-10 Codeforces handles: rating, max rating, rank/tier, country, organization, contribution and registration date.
Inputs: handles (required).
get_user_ratingGet Codeforces rating historyBRead-onlyIdempotent
Return a user's full contest rating history (newest first) with per-contest rating deltas, ranks, tier labels, best rating, biggest gain and biggest drop. Use for trend questions.
Inputs: handle (required), limit.
get_user_statsAnalyze Codeforces user performanceARead-onlyIdempotent
Compute derived analytics from a user's submission history: unique problems solved vs attempted, acceptance rate, verdict breakdown, favourite languages, strongest tags, solved-by-rating distribution and hardest solved problem. Answers 'how good is X' in one call.
Inputs: handle (required), sampleSize.
get_user_submissionsGet Codeforces user submissionsBRead-onlyIdempotent
Return a user's recent submissions, compacted to verdict, problem, language, runtime and memory. Raw Codeforces submission objects are very large; this trims them for LLM context.
Inputs: handle (required), from, count.
list_problemsList Codeforces problems by tag and ratingARead-onlyIdempotent
Browse the problemset with structured filters instead of a text query. Returns the most-solved problems matching ALL given tags within the rating range. Ideal for building practice ladders.
Inputs: tags, limit, maxRating, minRating.
search_problemsSearch Codeforces problemsARead-onlyIdempotent
Search the official Codeforces problemset by problem id ('158A', '158/A'), title, tag ('dp', 'greedy', 'binary search') or rating ('1500', '1200-1600'). Multi-word queries must match every token, so 'dp 1500' returns 1500-rated dynamic programming problems. Prefer this over scraping codeforces.com.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct resources and actions, and descriptions clarify the boundaries between users, problems, submissions, and contests. A few pairs still have some overlap, especially search_problems vs list_problems for problemset discovery and get_contest_list vs get_upcoming_contests for contest listing.
The set uses consistent snake_case with verb_noun naming such as get_user_info, get_user_rating, search_problems, and list_problems. There are minor deviations like get_contest_list instead of list_contests, and get_recent_submissions vs get_user_submissions, but the pattern remains readable and predictable.
At 17 tools, the surface is slightly above the typical 3-15 range, but the breadth is justified by covering problems, users, submissions, contests, and diagnostics. Each tool has a plausible role, though a couple of pairs could potentially be consolidated.
The read-only Codeforces domain is well covered across problem discovery, user analytics, submission history, contest listings, standings, and rating changes. Minor gaps remain, such as fetching a specific submission or full problem statement, with the latter explicitly limited by the upstream API.
Maintenance
Related MCP Connectors
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
660+ data tools for agents: TikTok, Douyin, Instagram, YouTube, X, weather, GitHub. Pay per call.
Related MCP Servers
- AlicenseAqualityDmaintenanceA complete, all-in-one MCP server for Codeforces, enabling AI assistants to access user profiles, compare users, search problems, get practice recommendations, and more.83MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to access Codeforces public data (users, contests, problems, etc.) via natural language or direct tool calls through Pipeworx gateway.55 npmMIT
- FlicenseAqualityCmaintenanceEnables coding agents to discover unsolved Codeforces practice problems, analyze tag performance, and inspect submissions, profiles, rating history, and upcoming contests through MCP-compatible clients.6-
- FlicenseNot gradedqualityBmaintenanceConnects Claude to the Codeforces public API, enabling retrieval of user submissions, profile info, rating history, contest standings, contest status, and contest lists through natural language.-