codeforces-mcp

Ein MCP-Server, der Coding-Agenten Zugriff auf Codeforces-Übungsdaten gibt. Er hilft dir, deine schwachen Tags zu verstehen und Aufgaben zu finden, die du noch nicht gelöst hast.

Der Server ist schreibgeschützt, verwendet die öffentliche Codeforces-API und erfordert keine Codeforces-Authentifizierung. Er funktioniert mit VS Code Copilot, Claude Desktop/Code und anderen MCP-Clients, die stdio-Server unterstützen.

Funktionen

• Aufgaben nach Rating und Tag finden, optional unter Ausschluss der bereits gelösten Aufgaben eines Benutzers.

• Die Tags eines Handles nach Lösungsrate und durchschnittlichem Rating gelöster Aufgaben einordnen.

• Aktuelle Einreichungen anzeigen und nach Status filtern.

• Profil und Ratingverlauf eines Benutzers anzeigen.

• Bevorstehende Contests auflisten.

• Ergebnisse als lesbares Markdown oder strukturiertes JSON zurückgeben.

• Antworten des vorgelagerten Dienstes lokal cachezone und eine angemessene Anforderungsrate durchsetzen.

Related MCP server: cf-mcp-orange

Voraussetzungen

• Python 3.10 oder neuer

• Ein Codeforces-Handle für benutzerspezifische Tools

• VS Code mit GitHub Copilot Agent-Modus, Claude oder einen anderen MCP-kompatiblen Client

Es ist kein API-Schlüssel erforderlich.

Installation

Kleanen, Repository und virtuelle Umgebung erstellen:

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

Umgebung aktivieren:

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

# macOS/Linux
source .venv/bin/activate

Paket installieren:

python -m pip install -e .

Für die Entwicklung auch die Test- und Lint-Abhängigkeiten installieren:

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

Bei der Installation wird der Befehl codeforces-mcp in der virtuellen Umgebung erstellt.

Verwendung mit VS Code Copilot

Das Repository enthält eine Workspace-Konfiguration unter .vscode/mcp.json. Unter Windows kann sie direkt auf das ausgecheckte venv verweisen:

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

Ersetze den Pfad durch den tatsächlichen Speicherort deines Klons. Verwende für macOS/Linux:

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

In VS Code:

1. Führe MCP: Open Workspace Folder Configuration über die Befehlspalette aus.

2. Füge den Server-Eintrag codeforces hinzu oder aktualisiere ihn.

3. Öffne Copilot Chat und wechsle in den Agent-Modus.

4. Öffne das Tools-Menü, starte oder aktiviere den codeforces-Server und erlaube die Tools.

Frag Copilot dann zum Beispiel:

Finde mir 5 ungelöste DP-Aufgaben mit Rating 1300-1500 für das Handle 3.141f.

Der Server verwendet stdio, daher startet und beendet VS Code ihn nach Bedarf. Du solltest keine zweite Instanz manuell starten, solange Copilot verbunden ist.

Verwendung mit Claude

Aktiviere die virtuelle Umgebung und registriere den Befehl bei Claude Code:

claude mcp add codeforces -- codeforces-mcp

Wenn sich der Befehl nicht in deinem PATH befindet, verwende die ausführbare Datei direkt:

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

Der entsprechende Befehl für macOS/Linux ist:

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

Tools

Alle Tools sind schreibgeschützt und unterstützen response_format, das entweder "markdown" (Standard) oder "json" ist.

codeforces_search_problems

Finde Aufgaben, die einfachsten zuerst. Setze exclude_solved_by auf ein Handle, möchte ich Aufgaben ausblenden, deren Status für dieses Handle OK ist.

Beispielanfrage:

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

Entsprechende Argumente:

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

codeforces_tag_performance

Berechnet für jeden Tag Versuche, gelöste Aufgaben, Lösungsrate und Ratings für ein Handle. Die Ergebnisse werden nach schwächster Lösungsrate zuerst sortiert. min_attempted verhindert, dass sehr kleine Stichproben das Ranking dominieren.

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

codeforces_recent_submissions

Liste die neuesten Einreichungen eines Handles auf. Verwende einen Status wie WRONG_ANSWER, TIME_LIMIT_EXCEEDED oder OK, um die Liste zu filtern.

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

codeforces_user_profile

Zeige das aktuelle Rating, das maximale Rating, den Rang und die Organisation eines Codes an.

{
  "handle": "3.141f"
}

codeforces_rating_history

Zeige die Ratingänderungen für jeden Contest, die ältesten zuerst. Setze limit, um nur die letzten Contests zurückzugeben.

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

codeforces_upcoming_contests

Liste Contests auflisten, die noch nicht begonnen haben, der Partner-Test zuerst.

{
  "limit": 5
}

Ausgabebeispiel

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

Das JSON-Format enthält dieselben typischen Daten für Anwendungen, die das Ergebnis programmatisch weiterzuverarbeiten müssen.

Cache und Ratenbegrenzung

Die Codeforces-API sieht etwa eine Anfrage alle zwei Sekunden vor. Der Client erzwingt eine Anforderungsrate und speichert Antworten standardmäßig unter ~/.cache/codeforces-mcp. Die Cache-Lebensdauer richtet sich nach der Änderungshäufigkeit der Daten: sechs Stunden für den Aufgabenkatalog, fünf Minuten für Einreichungen und eine Stunde für Nutzerprofile.

Fehlerbehebung

Server startet nicht

Prüfe, ob die ausführbare Datei in der für deine MCP-Konfiguration verwendeten Umgebung vorhanden ist:

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

./.venv/bin/codeforces-mcp

Wenn du in ein anderes venv installiert hast, aktualisiere den Pfad unter command in mcp.json.

Codeforces gibt einen Fehler zurück

Überprüfe die Schreibweise des Handles und versuche es später noch einmal. Der Server leitet aussagekräftige Fehlermeldungen von Codeforces an den Client weiter. Die öffentliche API kann außerdem vorübergehend limitiert oder nicht verfügbar sein.

Entwicklung

Führe vor dem Einreichen einer Änderung die deterministischen Prüfungen aus:

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

Live-Tests rufen Codeforces auf und sind optional:

pytest -m live -q

Lokale Commit-Daten umschreiben

Das Repo enthält rebase-commits-to-july.sh, um alle Commits auf dem aktuellen Branch um den Zeitraum des 14. und 15. Juli 2026 umzuschreiben. Es erstellt vor einer Verlaufsänderung einen Backup-Branch:

bash rebase-commits-to-july.sh

Der Arbeitsbaum muss sauber sein, und das Skript muss von einem benannten Branch ausgeführt werden. Es schreibt Commit-IDs neu, du solltest es also nicht ohne Koordination auf einem gemeinsamen Branch verwenden. Um den ursprünglichen Abschlusscommit wiederherzustellen, verwende den vom Skript Genannten:

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

Lies SPEC.md, bevor du das Verhalten der Tools änderst. Es definiert die Verträge und Abnahmekriterien, und zu jedem Kriterium gehört ein Vertragstest.

Projektstruktur

Beiträge

1. Eröffne ein Issue für einen Bug oder einen gewünschten neuen Verhaltens.

2. Aktualisiere SPEC.md und dazugehörigen Vertragstest bevor du das Verhalten änderst.

3. Halte die Tool-Logik in src/codeforces_mcp/tools/ frei von MCP-Importen.

4. Führe die Entwicklungsprüfungen aus und füge die relevanten Testausgaben in den Pull-Request.

Bitte vermeiden Sie das Committen von virtuellen Umgebungen, Caches, Build-Artefakten oder API-Aufzeichnungen mit personenbezogenen Daten. Die .gitignore des Repository bereits die lokalen Entwicklungsartefakte, die this project exposed.

Weitere int

• SPEC.md – Tool-Verträge und Design-Entscheidungen

• docs/TECHNICAL-OVERVIEW.md – Architektur und Implementierungsdetails

GXP26