cf-analyser

A local MCP server for analysing Codeforces activity: weekly practice summaries, problem recommendations, user comparisons, weak-topic detection, contest tracking, and rating progress. Backed by the public Codeforces API, with every request signed and authenticated for higher rate limits and reliability.

Requirements

• Python 3.14+

• uv

• A Codeforces API key and secret — generate one at https://codeforces.com/settings/api

Related MCP server: DevAssist MCP Server

Setup

1. Clone the repo and install dependencies:

   git clone <this-repo-url>
   cd cf_analyser
   uv sync

2. Copy .env.example to .env and fill in your API key/secret:

   cp .env.example .env

   (.env isn't loaded automatically — it's just there as a reference for the values you'll put into your MCP client config in the next step.)

Adding to Claude Desktop / Claude Code

Add an MCP server entry pointing at this project. Find the absolute path to uv with which uv, and use the absolute path to wherever you cloned this repo — Claude launches MCP servers without your shell's PATH, so a bare "uv" command may fail to resolve.

Claude Desktop: edit claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json). Claude Code: use claude mcp add or edit its MCP config the same way.

{
  "mcpServers": {
    "cf-analyser": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--directory", "/absolute/path/to/cf_analyser", "cf-analyser"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cf_analyser/src",
        "CF_API_KEY": "your-api-key",
        "CF_API_SECRET": "your-api-secret"
      }
    }
  }
}

Restart Claude Desktop/Code afterwards so it picks up the new server.

Running standalone (for testing)

CF_API_KEY=... CF_API_SECRET=... PYTHONPATH=src uv run cf-analyser

Or use the MCP inspector to poke at tools interactively in the browser:

CF_API_KEY=... CF_API_SECRET=... PYTHONPATH=src uv run mcp dev src/cf_analyser/server.py

Tools

• get_user_profile(handle) — rank, rating, max rating, contribution, rating trend.

• analyse_activity(handle, days=7) — problems solved/attempted, verdict breakdown, tags practiced, difficulty range.

• recommend_problems(handle, count=5, target_rating=None, tags=None) — unsolved problems near the user's level.

• compare_users(handle1, handle2) — side-by-side rating, solved counts, shared solves, tag strength.

• weak_topics(handle, min_attempts=3) — tags with the lowest solve rate.

• upcoming_contests(count=5) — next contests, soonest first.

• contest_performance(handle, contest_id) — rank, points, penalty, and rating delta for one contest.

• solve_streak(handle) — current and longest daily solve streak.

• rating_progress(handle) — rating history summary, best/worst contest, plateau detection.

Once connected, just ask Claude things like "analyse my Codeforces week", "recommend some problems for me", or "compare me with tourist" — it'll call the right tool automatically.

Troubleshooting

• Server doesn't show up in Claude: double-check the command path is absolute and correct (which uv), and that --directory points at this repo.

• "CF_API_KEY and CF_API_SECRET must be set": the env block in your MCP config is missing or has empty values.

• Tool calls fail with a Codeforces error message: usually an invalid handle, or an invalid/expired API key or secret — regenerate one at https://codeforces.com/settings/api if needed.

License

I never understood what this actually is