Model Context Protocol Official API · Read-only · Dual runtime

Give your AI a seat at Codeforces

17 read-only tools that turn the official Codeforces API into compact, structured JSON — problem search, practice ladders, rating history, performance analytics, standings and live contests — for Claude, Cursor, Cline and any MCP client. Same tools, same outputs, in Node.js and Python.

$ npx -y @iamrudhresh/mcp-server-codeforces
● 17 tools ● Node.js & Python ● stdio & Streamable HTTP ● No credentials ● 283 passing checks

Core capabilities

Everything a competitive programmer asks about

A

Problemset search

Find problems by id (158A), title, tag or rating. Multi-word queries use AND semantics, so dp 1500 means exactly that.

↗

Rating history & analytics

Per-contest deltas, best rating, biggest swing, acceptance rate, verdict mix, favourite languages, strongest tags and a solved-by-rating curve.

#1

Contests & standings

Upcoming rounds with hours-to-start, standings windows filtered by handle, post-contest rating changes and per-contest submissions.

✓

Read-only by construction

No login, no cookies, no code execution, no submissions. get_capabilities states the contract so agents never try.

⌛

Rate-limit aware

A serialized throttle, TTL cache and exponential backoff on Call limit exceeded, 429, 5xx and timeouts keep you inside Codeforces' limits.

{}

Context-window safe

The 20 MB problemset, 26 MB rated list and full standings are normalized and capped. Submissions are compacted to the fields that matter.

Client setup

Copy a config, restart your client

claude_desktop_config.json
Loading config...

Tool explorer

17 tools, one contract

Arguments shown in Node.js camelCase; the Python runtime uses snake_case equivalents.

Built-in tier labels

Every rating in every response carries its Codeforces rank name.

newbie
<1200
pupil
1200
specialist
1400
expert
1600
cand. master
1900
master
2100
intl. master
2300
grandmaster
2400
intl. GM
2600
legendary
3000+

Architecture

One pipeline, two runtimes

1 · tools
Schema validation
zod / type hints, handle regex, bounds
2 · api
Operations
compaction, analytics, local windowing
3 · http
Throttle & cache
1.1 s spacing, TTL cache, backoff
4 · upstream
codeforces.com/api
lang=en, host-pinned, size-capped

Node.js runtime — src/

  • server.js · STDIO entrypoint
  • tools.js · 17 registrations
  • api.js · operations & analytics
  • http.js · throttle, cache, retries
  • normalize.js · pure scoring

Python runtime — app/

  • run_server.py · STDIO or --http
  • tools/*.py · FastMCP registrations
  • client/api.py · mirrors api.js
  • client/http.py · async httpx client
  • main.py · Streamable HTTP ASGI app

Quality

Hardened against real API quirks

Notable fixes

  • ✓English names — Codeforces answers in Russian unless lang=en is sent.
  • ✓Standings work anonymously — extra params are rejected upstream, so paging is done locally.
  • ✓Unbounded leaderboard and contest payloads are capped.
  • ✓Concurrent calls can no longer slip past the rate limiter.
  • ✓Searching 1500 returns 1500-rated problems, not contest 1500.
  • ✓One shared HTTP client, reused and closed cleanly; zero unpublished dependencies.

Test suites

Node · offline unit89 / 89
Node · live API smoke21 / 21
Node · MCP over stdio86 / 86
Python · unit, mocked API, MCP stdio78 / 78
Python · live API9 / 9

CI runs the offline suites on Node 20 / 22 / 24 and Python 3.10 / 3.12 / 3.13.