codeforces-mcp

一个 MCP 服务器，为编码智能体提供 Codeforces 练习数据的访问。它可以帮助你了解自己的薄弱标签（tags），并找出你尚未解决的题目。

该服务器是只读的，使用公共 Codeforces API，无需任何 Codeforces 认证。它可与 VS Code Copilot、Claude Desktop/Code 以及其他支持 stdio 服务器的 MCP 客户端配合使用。

功能

• 按评分和标签查找题目，并可选地排除某个用户已解决的题目。

• 按通过率和平均已解决评分对某个用户名的标签进行排序。

• 查看最近的提交记录，并按评判结果（verdict）过滤。

• 查看用户的个人资料和评分历史。

• 列出即将到来的比赛。

• 以可读的 Markdown 或结构化 JSON 返回结果。

• 在本地缓存上游响应，并强制一个礼貌的请求速率。

Related MCP server: cf-mcp-orange

环境要求

• Python 3.10 或更高版本

• 用于用户相关工具的 Codeforces 用户名（handle）

• 带有 GitHub Copilot Agent 模式的 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 .

开发模式下，同时安装测试和 lint 依赖：

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

安装完成后会在虚拟环境中创建 codeforces-mcp 命令。

与 VS Code Copilot 一起使用

仓库包含位于 .vscode/mcp.json 的工作区配置。在 Windows 上，它可以直接指向检出的虚拟环境：

{
  "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 找 5 道评分在对解题结果（OK）中尚未解决的 DP 题目。

服务器使用 stdio，因此 VS Code 会在需要时自动启动或停止它。在 Copilot 连接期间，请勿手动再启动一个副本。

与 Claude 一起使用

激活虚拟环境后，将该命令注册到 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

按难度从易到难查找题目。设置 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
}

codeforces_tag_performance

计算某个用户名的每个标签下的尝试次数、通过数、通过率和评分。结果按通过率从低到高排序。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

显示某个用户名的当前评分、最高评分、段位（rank）和所属组织。

{
  "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 约为每两秒一个请求。客户端会强制速率限制，并默认将响应存储于 ~/.cache/codeforces-mcp。缓存生命周期反映数据变化的频率：题目集合为六小时，提交记录为五分钟，用户资料为一小时。

故障排除

服务器无法启动

检查 MCP 配置所使用的环境中是否存在该可执行文件：

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

./.venv/bin/codeforces-mcp

如果你安装到了另一个虚拟环境，请更新 mcp.json 中的 command 路径。

Codeforces 返回错误

检查用户名的拼写，并稍后重试。服务器会将可操作的 Codeforces 错误注释透传给客户端。公共 API 也可能暂时受到速率限制或不可用。

开发

提交变更前先运行确定性检查：

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

实际调用 Codeforces 的在线测试为可选：

pytest -m live -q

重写本地提交日期

仓库中包含 rebase-commits-to-july.sh，用于将当前分支的所有提交重写到 2026 年 7 月 14 日至 15 日之间。它在改写历史前会先创建备份分支：

bash rebase-commits-to-july.sh

工作树必须干净，且脚本必须在已命名分支上运行。该脚本会重写提交 ID，因此不要在未经协调的情况下用于共享分支。要恢复原始顶端提交，可使用脚本输出的备份分支：

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

在更改工具行为之前，请阅读 SPEC.md。它定义了契约和验收标准，每个标准都有对应的契约测试。

项目结构

参与贡献

1. 对于 bug 或行为变更建议，先开启 issue。

2. 在更改行为之前，先更新 SPEC.md 及其契约测试。

3. 保持 src/codeforces_mcp/tools/ 中的工具逻辑不依赖 MCP 的导入。

4. 提交前运行开发检查，并在 pull request 中包含相关测试输出。

请避免提交虚拟环境、缓存、构建输出或包含个人数据的 API 录音。仓库的 .gitignore 已排除了本项目创建的本地开发文件。

相关文档

• SPEC.md - 工具契约与设计决策

• docs/TECHNICAL-OVERVIEW.md - 架构与实现细节