codechef-mcp
Provides tools for interacting with CodeChef, including user profile analytics such as rating history, activity heatmaps, solved problems, and user comparisons, plus contest and problem workflows like opening contests, listing and fetching problems, generating tests, submitting solutions, and polling verdicts.
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., "@codechef-mcp show my CodeChef profile and recent rating changes"
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.
codechef-mcp (Unified Edition)
The unified, complete Model Context Protocol (MCP) server for CodeChef. It bridges AI assistants (such as Claude Desktop, Cursor, OpenCode, and Gemini) with CodeChef for both User Profiling & Analytics and Contest Participation & Problem Solving.
Available in two seamless runtimes:
Node.js (ESM): Lightweight, zero-config stdio MCP server for profile analytics and contest browsing.
Python (FastMCP): Full-featured engine supporting all tools, Docker sandbox code execution (C++, Python, Java, Go, Rust), and Playwright browser submission/verdict polling over STDIO or streamable HTTP/SSE.
π Capabilities & Tools
1. User Profiles & Analytics
Tool | Description |
| Structured user profile (name, stars, current/highest rating, division, global/country rank, problems solved, contest count, recent form). |
| Chronological contest history with rating after each contest, rating deltas ( |
| Submission heat map summary: total submissions, active days, average submissions per active day, busiest day, and monthly breakdown. |
| Contests participated in with problems solved in each, merged with rating change and rank. |
| Unique problems solved by a user mapped to their source contest. |
| Compact side-by-side comparison for 2β5 handles. |
2. Contest Management & Problem Solving
Tool | Description |
| Open contest and fetch metadata, start/end dates, problem list, and category details. |
| List all problems in a contest with codes, names, and submission counts. |
| Fetch clean problem statements (Markdown), constraints, time/memory limits, and sample test cases. |
| Static heuristic time/space complexity analysis (loop nesting depth & annotations). |
| Generate adversarial edge cases (minimum/maximum bounds, all identical, sorted, boundary flips, random cases). |
| Track attempted, solved, and remaining problems in an active contest. |
3. Execution, Submission & Automated Repair (Python Engine)
Tool | Description |
| Execute code in an isolated Docker sandbox with zero network access, memory limits, CPU caps, and timeouts (supports C++, Python, Java, Go, Rust). |
| Pre-submission confidence evaluation against sample and adversarial tests. |
| Automate CodeChef submission via Playwright browser automation. |
| Poll submission verdict (AC, WA, TLE, RE) and runtime metrics. |
| Self-repair diagnosis pipeline that analyzes failure causes and suggests code fixes. |
| Retrieve past submission history from local SQLite database. |
* Advanced execution and submission tools run via the Python engine.
Related MCP server: cf-mcp-orange
π Project Structure
codechef-mcp/
β
βββ app/ # Python FastMCP Server
β βββ browser/ # Profile scrapers, Playwright submitters, API clients
β β βββ profile.py # User profile, rating history, heatmap & comparison
β β βββ contest.py # Contest metadata & problem list fetching
β β βββ problem.py # Problem statement & sample test parser
β β βββ login.py # Playwright authentication manager
β β βββ submission.py # Code submission automation
β β βββ verdict.py # Verdict polling loop
β βββ models/ # SQLAlchemy SQLite schema (contests, submissions, logs)
β βββ retry_engine/ # Failure diagnostic & repair pipeline
β βββ sandbox/ # Docker runner & multi-language configurations
β βββ solver/ # Sequential contest solver state
β βββ tools/ # FastMCP tool registrations (18 tools)
β βββ utils/ # Structured logging & Redis/in-memory cache
β βββ config.py # Configuration loader
β βββ main.py # Streamable HTTP ASGI app
β βββ mcp_server.py # FastMCP server instance
β
βββ src/ # Node.js MCP Server
β βββ api.js # Node API router
β βββ contest.js # Contest metadata, problem statement & complexity analyzer
β βββ errors.js # Error definitions
β βββ http.js # HTTP fetch client with caching & rate limits
β βββ parse.js # Profile HTML & inline script JSON parser
β βββ server.js # Stdio server entrypoint
β βββ tools.js # Stdio tool definitions (11 tools)
β
βββ tests/ # Python test suite (33 unit tests)
βββ test/ # Node.js test suite (34 unit tests)
βββ docs/ # PRD and cloud deployment guides (Fly.io, Render)
βββ Dockerfile # Container definition
βββ docker-compose.yml # Docker Compose definition
βββ run_server.py # Python server CLI runner (STDIO & HTTP)
βββ requirements.txt # Python dependencies
βββ package.json # Node.js package definitionπ οΈ Usage & Setup
Running via Node.js
1. Instant run via npx:
npx codechef-mcp2. Local installation:
npm install
npm test
npm startRunning via Python
1. Setup virtual environment:
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium2. Run Python tests:
pytest tests/ -v3. Run Python Server:
# STDIO Transport:
python run_server.py
# Streamable HTTP/SSE Transport:
python run_server.py --http --port 8000π Connecting to AI Clients
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"codechef": {
"command": "node",
"args": ["E:/PERSONAL/OpenSource/codechef-mcp/src/server.js"]
}
}
}Or for the Python full-suite server:
{
"mcpServers": {
"codechef": {
"command": "E:/PERSONAL/OpenSource/codechef-mcp/venv/Scripts/python.exe",
"args": ["E:/PERSONAL/OpenSource/codechef-mcp/run_server.py"]
}
}
}Cursor / Web Agents (HTTP/SSE)
Run:
python run_server.py --http --port 8000Connect to http://localhost:8000/mcp.
π License
MIT License.
Available Tools
11 toolscompare_usersCompare CodeChef usersARead-only
Fetch compact side-by-side profiles for 2-5 CodeChef handles: rating, stars, ranks, problems solved and contest count. Handy for 'who is better' or team-selection questions.
Inputs: handles (required).
generate_testsGenerate test casesARead-only
Generate adversarial and edge-case test inputs (minimums, maximums, duplicates, sorted, random) for a problem.
Inputs: problemCode (required), constraints.
get_activityGet CodeChef submission activityARead-only
Summarize a user's submission heat map over a time window: total submissions, active days, average per active day, busiest day and monthly totals. Answers 'how active is X' without loading the heat map image or HTML.
Inputs: handle (required), days.
get_contestsGet CodeChef contest resultsARead-only
List a user's contests (newest first) with the problems solved in each, plus rank and rating change where available. Use this for 'what has X solved recently' or per-contest performance.
Inputs: handle (required), limit.
get_problemGet CodeChef problem detailsARead-only
Fetch full problem statement, constraints, time/memory limits, and sample test cases.
Inputs: contestCode (required), problemCode (required).
get_profileGet CodeChef profileARead-only
Fetch a CodeChef user's profile as compact structured JSON: name, star rating, current and highest rating, division, global rank, country rank, problems solved, contests participated, latest contest and recent form. Prefer this over downloading and parsing the profile HTML page.
Inputs: handle (required).
get_rating_historyGet CodeChef rating historyARead-only
Return a user's contest rating history (newest first) with rating after each contest, rating change (delta) and rank. Useful for trends, streaks and 'how has X improved' questions.
Inputs: handle (required), limit.
get_solved_problemsGet CodeChef solved problemsARead-only
Return the unique problem names a user has solved (as listed on their profile), with the contest each came from, plus their reported total solved count. Capped by 'limit' to protect context size.
Inputs: handle (required), limit.
list_problemsList CodeChef contest problemsARead-only
List all problems in a CodeChef contest with codes, names, and submission counts.
Inputs: contestCode (required).
open_contestOpen CodeChef contestARead-only
Open a CodeChef contest, fetch problem list, start/end dates, and contest metadata.
Inputs: contestCode (required).
validate_complexityValidate algorithmic complexityBRead-only
Estimate time and space complexity of code through static loop analysis and comment annotations.
Inputs: code (required), language.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 11 tools
Tools mostly target distinct facets: profile, rating history, activity, contests, solved problems, contest problem access, and code analysis. Some overlap exists between open_contest and list_problems for contest problem lists, and between get_rating_history and get_contests for per-contest rating data, but descriptions largely clarify intended use.
All tool names use snake_case and follow a predictable verb_noun or verb_noun_plural pattern, such as get_profile, list_problems, compare_users, and generate_tests. There are no mixed casing styles or vague names.
With 11 tools, the server is well-scoped for CodeChef profile, contest, and problem analysis. The count is neither thin nor bloated, and each tool has a plausible role.
The surface covers the major read-only workflows: profiles, rating trends, activity, contests, solved problems, comparisons, contest problems, complexity validation, and test generation. Minor gaps include global problem search, submission/code retrieval, and contest leaderboards, but core workflows are supported.
Maintenance
Related MCP Connectors
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analyβ¦
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Build Apps and run code in 30 languages β sandboxed, with persistent sessions for agent loops.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to participate in CodeChef contests by fetching problems, generating and testing solutions in a secure sandbox, and submitting answers.-
- 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
- AlicenseAqualityBmaintenanceConnects AI assistants to the Repovive competitive-programming platform, enabling them to browse problems and contests, judge and submit code for real verdicts, track ratings, communicate with users, and author verified problems and rounds.102MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT users to retrieve exact programming problems, submit C/C++ solutions only when explicitly requested, and track real judging verdicts through authenticated account linking.MIT