Skip to main content
Glama

codechef-mcp (Unified Edition)

npm license node python

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

get_profile

Structured user profile (name, stars, current/highest rating, division, global/country rank, problems solved, contest count, recent form).

get_rating_history

Chronological contest history with rating after each contest, rating deltas (ratingChange), and ranks.

get_activity

Submission heat map summary: total submissions, active days, average submissions per active day, busiest day, and monthly breakdown.

get_contests

Contests participated in with problems solved in each, merged with rating change and rank.

get_solved_problems

Unique problems solved by a user mapped to their source contest.

compare_users

Compact side-by-side comparison for 2–5 handles.

2. Contest Management & Problem Solving

Tool

Description

open_contest

Open contest and fetch metadata, start/end dates, problem list, and category details.

list_problems

List all problems in a contest with codes, names, and submission counts.

get_problem

Fetch clean problem statements (Markdown), constraints, time/memory limits, and sample test cases.

validate_complexity

Static heuristic time/space complexity analysis (loop nesting depth & annotations).

generate_tests

Generate adversarial edge cases (minimum/maximum bounds, all identical, sorted, boundary flips, random cases).

get_contest_progress*

Track attempted, solved, and remaining problems in an active contest.

3. Execution, Submission & Automated Repair (Python Engine)

Tool

Description

run_code*

Execute code in an isolated Docker sandbox with zero network access, memory limits, CPU caps, and timeouts (supports C++, Python, Java, Go, Rust).

evaluate_confidence*

Pre-submission confidence evaluation against sample and adversarial tests.

submit_solution*

Automate CodeChef submission via Playwright browser automation.

get_submission_status*

Poll submission verdict (AC, WA, TLE, RE) and runtime metrics.

retry_solution*

Self-repair diagnosis pipeline that analyzes failure causes and suggests code fixes.

get_submission_history*

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

2. Local installation:

npm install
npm test
npm start

Running 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 chromium

2. Run Python tests:

pytest tests/ -v

3. 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 8000

Connect to http://localhost:8000/mcp.


πŸ“„ License

MIT License.

Available Tools

11 tools
compare_usersCompare CodeChef usersA
Read-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 casesA
Read-only

Generate adversarial and edge-case test inputs (minimums, maximums, duplicates, sorted, random) for a problem.

Inputs: problemCode (required), constraints.

get_activityGet CodeChef submission activityA
Read-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 resultsA
Read-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 detailsA
Read-only

Fetch full problem statement, constraints, time/memory limits, and sample test cases.

Inputs: contestCode (required), problemCode (required).

get_profileGet CodeChef profileA
Read-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 historyA
Read-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 problemsA
Read-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 problemsA
Read-only

List all problems in a CodeChef contest with codes, names, and submission counts.

Inputs: contestCode (required).

open_contestOpen CodeChef contestA
Read-only

Open a CodeChef contest, fetch problem list, start/end dates, and contest metadata.

Inputs: contestCode (required).

validate_complexityValidate algorithmic complexityB
Read-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

    A3.9/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A complete, all-in-one MCP server for Codeforces, enabling AI assistants to access user profiles, compare users, search problems, get practice recommendations, and more.
      8
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects 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.
      102
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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