codeforces-mcp

codeforces-mcp

An MCP server that gives coding agents access to Codeforces practice data. It helpsyou understand your weak tags and find problems you have not already solved.

The server is read-only, uses the public Codeforces API, and requires no Codeforcesauthentication. It works with VS Code Copilot, Claude Desktop/Code, and other MCPclients that support stdio servers.

Features

• Find problems by rating and tag, optionally excluding a user's solved problems.
• Rank a handle's tags by solve rate and average solved rating.
• Review recent submissions and filter by verdict.
• Inspect a user's profile and rating history.
• List upcoming contests.
• Return results as readable Markdown or structured JSON.
• Cache upstream responses locally and enforce a polite request rate.

Requirements

• Python 3.10 or newer
• A Codeforces handle for user-specific tools
• VS Code with GitHub Copilot Agent mode, Claude, or another MCP-compatible client

No API key is required.

Installation

Clone the repository and create a virtual environment:

git clone https://github.com/<owner>/codeforces-mcp.git
cd codeforces-mcp
python -m venv .venv

Activate the environment:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

Install the package:

python -m pip install -e .

For development, install the test and lint dependencies too:

python -m pip install -e ".[dev]"

The installation creates the codeforces-mcp command in the virtual environment.

Use With VS Code Copilot

The repository includes a workspace configuration at .vscode/mcp.json. On Windows,it can point directly to the checked-out venv:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "E:\\path\\to\\codeforces-mcp\\.venv\\Scripts\\codeforces-mcp.exe"
    }
  }
}

Replace the path with the actual location of your clone. For macOS/Linux, use:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "/path/to/codeforces-mcp/.venv/bin/codeforces-mcp"
    }
  }
}

In VS Code:

1. Run MCP: Open Workspace Folder Configuration from the Command Palette.
2. Add or update the codeforces server entry.
3. Open Copilot Chat and switch to Agent mode.
4. Open the tools menu, start or enable the codeforces server, and allow the tools.

Then ask Copilot something like:

Find me 5 unsolved DP problems rated 1300-1500 for handle 3.141f.

The server uses stdio, so VS Code starts and stops it as needed. Do not start a secondcopy manually while Copilot is connected.

Use With Claude

After activating the venv, register the command with Claude Code:

claude mcp add codeforces -- codeforces-mcp

If the command is not on your PATH, use the executable directly.

claude mcp add codeforces -- .\.venv\Scripts\codeforces-mcp.exe

The equivalent macOS/Linux command is:

claude mcp add codeforces -- .venv/bin/codeforces-mcp

Tools

All tools are read-only and support response_format, which is either "markdown"(the default) or "json".

codeforces_search_problems

Find problems, easiest first. Set exclude_solved_by to hide problems whose verdictfor that handle is OK.

Example request:

Find 5 unsolved dp problems rated 1300-1500 for 3.141f.

Equivalent arguments:

{
  "min_rating": 1300,
  "max_rating": 1500,
  "tags": ["dp"],
  "exclude_solved_by": "3.141f",
  "limit": 5
}

codeforces_tag_performance

Compute per-tag attempts, solves, solve rate, and ratings for a handle. Results areordered from weakest solve rate first. min_attempted prevents very small samplesfrom dominating the ranking.

{
  "handle": "3.141f",
  "min_attempted": 8,
  "response_format": "markdown"
}

codeforces_recent_submissions

List a handle's newest submissions. Use verdict such as WRONG_ANSWER,TIME_LIMIT_EXCEEDED, or OK to filter the list.

{
  "handle": "3.141f",
  "verdict": "WRONG_ANSWER",
  "limit": 10
}

codeforces_user_profile

Show a handle's current rating, maximum rating, rank, and organization.

{
  "handle": "3.141f"
}

codeforces_rating_history

Show contest-by-contest rating changes, oldest first. Set limit to return only themost recent contests.

{
  "handle": "3.141f",
  "limit": 10
}

codeforces_upcoming_contests

List contests that have not started yet, soonest first.

{
  "limit": 5
}

Output Example

**5 of 208 matching problems** (offset 0, more available)

| Rating | Problem | Tags | Link |
| --- | --- | --- | --- |
| 1300 | 189A - Cut Ribbon | brute force, dp | https://codeforces.com/problemset/problem/189/A |
| 1300 | 234C - Weather | dp, implementation | https://codeforces.com/problemset/problem/234/C |
| 1300 | 416B - Art Union | brute force, dp, implementation | https://codeforces.com/problemset/problem/416/B |

The JSON format contains the same typed data for applications that need to processthe result programmatically.

Cache and Rate Limits

The Codeforces API documents approximately one request every two seconds. The clientenforces a rate limit and stores responses in ~/.cache/codeforces-mcp by default.Cache lifetimes reflect how often data changes: six hours for the problem set, fiveminutes for submissions, and one hour for user profiles.

Troubleshooting

Server does not start

Check that the executable exists in the environment used by your MCP configuration:

Test-Path .\.venv\Scripts\codeforces-mcp.exe

./.venv/bin/codeforces-mcp

If you installed into a different venv, update the command path in mcp.json.

Codeforces returns an error

Check the handle spelling and try again later. The server passes actionable Codeforceserror comments through to the client. The public API can also be temporarily ratelimited or unavailable.

Development

Run the deterministic checks before submitting a change:

ruff check .
mypy src/
pytest tests/contract -q
python eval/run_eval.py

Live tests call Codeforces and are opt-in:

pytest -m live -q

Rewrite Local Commit Dates

The repository includes rebase-commits-to-july.sh for rewriting all commitson the current branch across 14 and 15 July 2026. It creates a backup branch beforechanging history:

bash rebase-commits-to-july.sh

The working tree must be clean, and the script must be run from a named branch. Itrewrites commit IDs, so do not use it on a shared branch without coordination. Torestore the original tip, use the backup branch printed by the script:

git reset --hard backup/pre-date-rebase-<timestamp>

Read SPEC.md before changing tool behavior. It defines the contracts andacceptance criteria, and each criterion has a corresponding contract test.

Project Layout

Contributing

1. Open an issue for a bug or proposed behavior change.
2. Update SPEC.md and its contract test before changing behavior.
3. Keep tool logic in src/codeforces_mcp/tools/ free of MCP imports.
4. Run the development checks and include relevant test output in the pull request.

Please avoid committing virtual environments, caches, build output, or API recordingscontaining personal data. The repository .gitignore already excludes the localdevelopment artifacts created by this project.

Related Documentation

• SPEC.md - tool contracts and design decisions
• docs/TECHNICAL-OVERVIEW.md - architecture and implementation details