codeforces-mcp

코딩 에이전트에게 Codeforces 연습 데이터에 대한 접근을 제공하는 MCP 서버입니다. 취약한 태그를 파악하고 아직 풀지 않은 문제를 찾는 데 도움을 줍니다.

이 서버는 읽기 전용이며, 공개 Codeforces API를 사용하고 Codeforces 인증이 필요하지 않습니다. VS Code Copilot, Claude Desktop/Code 및 stdio 서버를 지원하는 기타 MCP 클라이언트와 함께 동작합니다.

기능

• 난이도와 태그로 문제를 찾고, 선택적으로 특정 사용자가 이미 해결한 문제를 제외할 수 있습니다.

• 핸들의 태그를 해결율과 평균 해결 난이도 순으로 순위화합니다.

• 최근 제출 내역을 확인하고 채점 결과(verdict)로 필터링합니다.

• 사용자 프로필과 레이팅 기록을 조회합니다.

• 다가오는 콘테스트 목록을 표시합니다.

• 결과를 읽기 쉬운 Markdown 또는 구조화된 JSON으로 반환합니다.

• 상위 응답을 로컬에 캐시하고 적절한 요청 속도를 준수합니다.

Related MCP server: cf-mcp-orange

요구 사항

• Python 3.10 이상

• 사용자별 도구를 위한 Codeforces 핸들

• GitHub Copilot 에이전트 모드가 있는 VS Code, 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 .

개발 목적으로는 테스트 및 린트 의존성도 함께 설치합니다.

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. codeforces 서버 항목을 추가하거나 업데이트합니다.

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을 지원합니다. "markdown"(기본값) 또는 "json"을 값으로 가집니다.

codeforces_search_problems

문제를 가장 쉬운 것부터 찾습니다. 해당 handle의 채점 결과가 OK인 문제를 표시에서 제외하려면 exclude_solved_by에 handle을 설정하세요.

요청 예시:

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
}

codeforces_get_tag_performance

핸들에 대해 태그별 시도 횟수, 해결 횟수, 해결율, 난이도를 계산합니다. 결과는 해결율이 가장 높은 약한 태그부터 정렬됩니다. min_attempted가 아주 작은 표본이 순위를 주도하는 것을 방지합니다.

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

codeforces_recent_submissions

핸들의 가장 최근 제출을 나열합니다. WRONG_ANSWER, TIME_LIMIT_EXCEEDED 또는 OK 같은 verdict 값을 사용하여 목록을 필터링할 수 있습니다.

{
  "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초에 13개의 요청으로 문서화되어 있습니다. 클라이언트는 요청 속도를 강제하며 기본적으로 ~/.cache/net```/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

작업 트리는 깨끗해야 하며 스크립트는 이름이 있는 브랜치에서 실행해야 합니다. 커밋 aaaaddd를 다시 작성하므로 공유 브랜치에서는 사전 합의 없이 실행하지 않습니다. 되돌리려면 스크립트가 출력한 백업 브랜치를 사용하세요.

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

도구 동작을 변경하기 전에 SPEC.md를 읽어 이를 토대와 계약을 정의합니다. 계약 테스트에 대응하는 계약 항목도 포함합니다.

프로젝트 구조

기여

1. 버그 또는 제안된 동작 변경에 대해 이슈를 등록하세요.

2. 동작을 변경하기 전에 SPEC.md와 그에 대한 계약 테스트를 업데이트하세요.

3. 도구 로직은 src/codeforces_mcp/tools/ 디렉터리에 MCP import 없이 유지하세요.

4. 개발 검사를 실행하고 관련 테스트 결과를 Pull Request에 담아 보내기세요.

가상 환경, 캐시, 빌드 출력 또는 개인 정보가 포함된 API 녹음본을 커밋하지 마세요. 저장소의 .gitignore는 이 프로젝트에서 생성되는 로컬 개발 산출물을 이미 제외합니다.

관련 문서

• SPEC.md – 도구 계약 및 설계 결정 사항

• docs/TECHNICAL-OVERVIEW.md – 아키텍처 및 구현 상세 정보