Skip to main content
Glama

mcp-server-codeforces

CI npm license node python

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 npx STDIO 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_problems

Search by id (158A, 158/A), title, tag (dp, binary search) or rating (1500, 1200-1600). Multi-word queries use AND semantics: dp 1500.

get_problem_metadata

Name, rating, tags, solved count and canonical URL for one problem.

list_problems

Practice ladder: most-solved problems carrying all given tags within a rating range.

Users & analytics

Tool

Description

get_user_info

Profiles for 1–10 handles: rating, max rating, rank, tier, country, organization, contribution.

get_user_rating

Rating history (newest first) with deltas, best rating, biggest gain and drop.

get_user_submissions

Recent submissions compacted to verdict / problem / language / time / memory.

get_user_stats

Derived analytics: solved vs attempted, acceptance rate, verdicts, languages, top tags, solved-by-rating curve.

compare_users

2–5 handles side by side, highest rated first.

get_rated_users

The rated leaderboard, optionally active-only or above a rating — always capped.

Contests

Tool

Description

get_contest_list

Contests filtered by phase (BEFORE, CODING, FINISHED, …) or from the gym.

get_upcoming_contests

Next scheduled contests, soonest first, with hours until start.

get_contest_standings

Contest info, problem list and a window of ranked rows; filter by handles.

get_contest_rating_changes

Old/new rating and delta per participant after a rated contest.

get_contest_status

Submissions in a contest, optionally for one handle.

get_recent_submissions

Live platform-wide submission feed.

Meta

Tool

Description

get_capabilities

Supported / degraded / unsupported operations (read-only contract).

get_health

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

npx -y mcp-server-codeforces

Claude 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-codeforces

Python

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/mcp

Remote 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=en is sent, so every request pins lang=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 applies from / count / handles locally.

  • 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.com are 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 metadata

Testing

# 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.com

CI 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

HOST / PORT

0.0.0.0 / 8000

HTTP transport bind

CODEFORCES_LANG

en

Language for names

MIN_REQUEST_INTERVAL

1.1

Seconds between upstream calls

REQUEST_TIMEOUT

30

Per-request timeout (s)

MAX_RETRIES

3

Retry attempts for transient failures

CACHE_TTL / PROBLEMSET_TTL

600 / 1800

Cache lifetimes (s)


Releasing

  1. Bump version in package.json, server.json, src/server.js and app/__init__.py.

  2. Tag and push: git tag v1.0.1 && git push --tags.

  3. 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 tools
compare_usersCompare Codeforces usersA
Read-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 capabilitiesA
Read-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 contestsA
Read-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 changesA
Read-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 standingsA
Read-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 submissionsA
Read-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 healthA
Read-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 metadataA
Read-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 leaderboardA
Read-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 submissionsA
Read-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 contestsA
Read-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 profileA
Read-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 historyB
Read-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 performanceA
Read-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 submissionsB
Read-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 ratingA
Read-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 problemsA
Read-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

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers