codeforces-mcp

コーディングエージェントにCodeforcesの練習データへのアクセスを提供するMCPサーバーです。自分の弱点タグを把握し、まだ解いていない問題を見つけるのに役立ちます。

このサーバーは読み取り専用で、公開のCodeforces APIを使用し、Codeforcesの認証は必要ありません。VS Code Copilot、Claude Desktop/Code、およびstdioサーバーをサポートするその他のMCP互換クライアントで動作します。

機能

• レーティングとタグで問題を検索し、オプションでユーザーが解いた問題を除外できます。

• ハンドルのタグを、正解率と平均正解レーティングでランク付けします。

• 最近の提出を確認し、判定でフィルタリングします。

• ユーザーのプロフィールとレーティング履歴を確認します。

• 開催予定のコンテストを一覧表示します。

• 結果を読みやすいMarkdownまたは構造化されたJSONで返します。

• 上流のレスポンスをローカルにキャッシュし、控えめなリクエストレートを適用します。

Related MCP server: cf-mcp-orange

要件

• Python 3.10以降

• ユーザー固有のツールに使用するCodeforcesハンドル

• VS Code（GitHub Copilot Agentモード）、Claude、またはその他のMCP対応クライアント

APIキーは不要です。

インストール

リポジトリをクローンして仮想環境を作成します：

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

仮想環境を有効にします：

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

# macOS/Linux
source .venv/bin/activate

パッケージをインストールします：

python -m pip install -e .

開発のために、テスト用とlint用の依存関係もインストールします：

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

インストールすると、仮想環境内に codeforces-mcp コマンドが作成されます。

VS Code Copilot で使用する

リポジトリには .vscode/mcp.json のワークスペース設定が含まれています。Windowsでは、チェックアウトしたvenvを直接参照できます：

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

パスは、実際にクローンした場所に置き換えてください。macOS/Linuxでは次のようにします：

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

VS Codeでの手順：

1. コマンドパレットから MCP: Open Workspace Folder Configuration を実行します。

2. 各コードサーバーのエントリを追加または更新します。

3. Copilot Chatを開き、Agent モードに切り替えます。

4. ツールメニューを開き、codeforcesサーバーを起動または有効にし、ツールを許可します。

その後、Copilot に次のように依頼します：

ハンドル 3.141f について、レーティング1300〜1500の未解決のDP問題を5つ見つけてください。

サーバーはstdioを使用するため、VS Codeは必要に応じてサーバーを起動・停止します。Copilot が接続している間は、手動でコピーを起動しないでください。

Claude で利用する

venvを有効にした後、Claude Code にコマンドを登録します：

claude mcp add codeforces -- codeforces-mcp

コマンドがPATHにない場合は、実行ファイルを直接使用します：

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

macOS/Linuxで対応するコマンドは次のとおりです：

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

ツール

すべてのツールは読み取り専用で、response_format に対応しています。response_format は "markdown"（デフォルト）または "json" です。

codeforces_search_problems

問題を易しい順に見つけます。exclude_solved_by を設定すると、そのハンドルで判定が OK の問題を非表示にできます。

リクエスト例：

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

同等の引数：

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

タグのパフォーマンス

ハンドルのタグごとに試行回数・正解数・正解率・レーティングを計算します。結果は正解率が低い順に並びます。min_attempted を設定すると、試行回数が非常に少ないサンプルがランキングを支配しないようにできます。

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

codeforces_recent_submissions

ハンドルの最新の提出を一覧表示します。verdict に WRONG_ANSWER、TIME_LIMIT_EXCEEDED、OK などを指定すると、一覧をフィルタリングできます。

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

codeforces_user_profile

ハンドルの現在のレーティング、最大レーティング、ランク、所属組織を表示します。

{
  "handle": "3.141f"
}

codeforces_rating_history

コンテストごとのレーティング変化を古い順に表示します。limit を設定すると、直近のコンテストのみを返します。

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

codeforces_upcoming_contests

開始前のコンテストを、開催が近い順に一覧表示します。

{
  "limit": 5
}

出力例

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

JSON形式には、アプリケーションが結果をプログラム的に処理するための、同じ型付きデータが含まれています。

キャッシュとレート制限

Codeforces API は約2秒に1リクエストのペースを推奨しています。クライアントはレート制限を適用し、レスポンスをデフォルトで ~/.cache/codeforces-mcp に保存します。キャッシュの有効期間はデータの更新頻度を反映し、問題セットは6時間、提出は5分、ユーザープロフィールは1時間です。

トラブルシューティング

サーバーが起動しない

MCP設定で使用している環境に実行ファイルが存在するか確認してください：

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

./.venv/bin/codeforces-mcp

別のvenvにインストールした場合は、mcp.json の command パスを更新してください。

Codeforces がエラーを返す

ハンドルの表記を確認し、少し待ってから再度試してください。サーバーは、対応可能なCodeforcesのエラーコメントをクライアントにそのまま渡します。公開APIが一時的にレート制限されたり、利用できない場合もあります。

開発

変更を送信する前に、決定論的チェックを実行してください：

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

ライブテストはCodeforces に実アクセスするため、オプトインです：

pytest -m live -q

ローカルコミット日の書き換え

リポジトリには、現在のブランチのすべてのコミットを2026年7月14日と15日付に書き換える rebase-commits-to-july.sh が含まれています。実行前に、バックアップ用ブランチを作成します：

bash rebase-commits-to-july.sh

作業ツリーがクリーンであることと、スクリプトを名前付きブランチから実行することが必要です。コミットIDが書き換わるため、共有ブランチでは他の関係者の合意なしに使用しないでください。元の最新コミットに戻すには、スクリプトが表示したバックアップブランチを使用してください：

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

ツールの動作を変更する前に、SPEC.md を読んでください。この文書には契約と受け入れ条件が定義されており、各条件には対応するテストテストがあります。

プロジェクト構成

コントリビューション

1. バグや変更提案は issue を開いてください。

2. 動作を変更する前に SPEC.md とその契約テストを更新してください。

3. ツールのロジックは src/codeforces_mcp/tools/ 内でMCPのインポートなしに保ってください。

4. 開発チェックを実行して、関連するそのテスト出力をプルリクエストに含めてください。

仮想環境、キャッシュ、ビルド成果物、個人データを含むAPI録音データはコミットしないでください。リポジトリの .gitignore は