codeforces-mcp

A production-grade Model Context Protocol (MCP) server that gives Claude deep, structured access to the Codeforces competitive programming platform.

Claude becomes your personal competitive programming coach, powered by your real Codeforces data.

What It Does

• Analyzes your submission history to find weaknesses and strengths
• Recommends problems tailored to your skill level and weak areas
• Generates roadmaps to reach a target rating
• Builds virtual contests matched to your level
• Tracks your progress, streaks, and trends over time
• Compares your profile with other users
• Finds problems your friends solved that you haven't

Quick Start

Install

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codeforces": {
      "command": "npx",
      "args": ["codeforces-mcp"],
      "env": {
        "CF_HANDLE": "your_codeforces_handle"
      }
    }
  }
}

That's the entire setup. No API keys. No login. No backend.

First Conversation

You: "Set up my profile"
Claude: "Got it! You're rated 1842 (Expert). I've loaded your submission history.
        Want me to find your weak spots or pull your last unsolved problem?"

Example Prompts

"What are my biggest weaknesses right now?"
"Find me 5 graph problems I haven't solved rated around my level"
"I want to hit 1600 in 2 months — make me a plan"
"How did I perform in my last 10 contests?"
"Give me a 2-hour virtual contest at my level"
"Compare me with tourist and Petr"
"Pull my last unsolved problem and help me with it"
"What should I upsolve from Codeforces Round 950?"
"Am I improving or plateauing? Be honest."
"What problems have my friends solved that I haven't?"
"What's the next contest and when does it start?"
"Which topic should I study this week to improve fastest?"

Tools

User Tools

Tool	Description
get_profile	Full user profile with rating, rank, solve count
get_submissions	Submission history, filterable by verdict
get_rating_history	Rating changes across all contests
get_solved_problems	All solved problems, deduplicated

Problem Tools

Tool	Description
get_problem	Fetch a specific problem (e.g., 1234A)
search_problems	Search by tags, rating, solved status
get_unsolved_problems	Problems attempted but never solved
get_last_unsolved	Most recently attempted unsolved problem
get_recommended_problems	Personalized recommendations based on weaknesses

Analysis Tools

Tool	Description
get_weakness_analysis	Tag x verdict matrix, rating ceiling/wall, trends
get_contest_performance	Contest stats with division breakdown
get_progress_report	Period report with streaks and comparisons
get_roadmap	Weekly plan to reach a target rating

Contest Tools

Tool	Description
get_upcoming_contests	Upcoming contests within N days
get_contest_standings	Standings for a specific contest
get_user_contest_history	Contest participation history
build_virtual_contest	Personalized virtual contest builder
get_upsolving_list	Unsolved problems from a contest

Compare Tools

Tool	Description
compare_users	Side-by-side comparison of users
get_problems_friends_solved	Problems friends solved that you haven't

Environment Variables

Variable	Required	Description
CF_HANDLE	Recommended	Default handle for "my" queries
CF_CACHE_TTL	Optional	Override default cache TTL (seconds)
CF_REQUEST_DELAY	Optional	Request delay in ms (default 250)
CF_LOG_LEVEL	Optional	debug / info / error

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Project Structure

src/
  server.ts          # MCP server entry, tool registration
  api/
    client.ts        # CF API client with rate limiting + caching
    cache.ts         # TTL cache
    endpoints.ts     # API endpoint definitions
  tools/
    user.ts          # Profile, submissions, rating, solved
    problems.ts      # Search, unsolved, recommendations
    analysis.ts      # Weakness, contest perf, progress, roadmap
    contests.ts      # Upcoming, standings, history, virtual
    compare.ts       # User comparison, friend problems
  engine/
    weakness.ts      # Tag x verdict matrix analysis
    recommender.ts   # Problem recommendation algorithm
    roadmap.ts       # Rating goal -> weekly plan
    virtual.ts       # Virtual contest builder
  types/
    cf.ts            # Zod schemas for CF API responses
    mcp.ts           # Tool input/output types
  utils/
    constants.ts     # Tags, rating bands, tier names
    math.ts          # Statistical helpers
    format.ts        # Output formatters

Contributing

1. Create or add to a file in src/tools/
2. Define a Zod input schema in src/types/mcp.ts
3. Implement the handler with error handling
4. Register in src/server.ts
5. Add a unit test with fixture data
6. Submit a PR

License

MIT