BIT101 MCP

一个面向北京理工大学学生的本地、只读 Model Context Protocol（MCP） 服务。它把 BIT101 社区内容、课程评价、个人课表、成绩和乐学日历转换为 Agent 容易理解的结构化数据，让你可以直接用自然语言提问。

能做什么

• 总结今天的 BIT101 帖子，或按关键词搜索历史讨论

• 查询课程、教师和历年学生评价

• 获取今天、本周、下周或指定学期的课表

• 查询成绩、学分、班级平均分和最高分（上游提供时）

• 查询未来一段时间的乐学日历事件

• 将不同来源的数据组合起来回答问题，例如“大家如何评价我下学期课程的老师”

所有工具均为只读。项目不能发帖、点赞、评论、提交作业、改成绩或修改任何学校数据。

Related MCP server: MCP-Server-CollageAI

实机演示

以下截图来自 Windows 上的 OpenCode cli 实机调用。具体回答由所用模型根据 MCP 返回的数据生成，不代表项目作者的观点，也可能随模型和数据更新而变化。

今日帖子总结

Agent 调用 list_today_posts 获取当天帖子，再按标题、内容和互动情况生成简短摘要。

教师与课程评价

Agent 先搜索教师对应的课程，再调用 get_course_reviews 聚合课程元数据、评分、评论和历史信息。

专业方向讨论

当课程库没有完全匹配的条目时，Agent 可以继续搜索 BIT101 帖子并读取相关讨论，展示了多个 MCP 工具串联使用的效果。

乐学日历

Agent 可以查询 7～90 天内的乐学事件。有效日历没有近期任务时会正常返回空列表，而不是把“没有任务”误判为接口故障。

使用前准备

目前推荐环境：

• Windows 10/11，或带桌面浏览器和可用系统 keyring 的 Linux（Fedora 43 + niri 已实测）

• Python 3.11 或更高版本

• uv

• 支持本地 stdio MCP 的客户端，例如 Codex、OpenCode、Cursor 或 Claude Code

• BIT101 账号

• 查询课表、成绩时，还需要北京理工大学统一身份认证账号；某些登录可能需要短信验证

• 查询乐学时，需要从乐学导出一次私人日历订阅地址

安装

Tell your Agent（推荐）

如果你的 Agent 可以执行终端命令和修改自己的 MCP 配置，可以直接把下面这段话发给它：

请帮我安装并配置 BIT101 MCP：
https://github.com/tiny-paris/BIT101-mcp

要求：
1. 先阅读仓库 README，尤其是“认证、安全与隐私”部分，并告诉我它会访问哪些服务。
2. 检查本机是否安装 Python 3.11+、Git 和 uv；缺少时说明后再安装。
3. 优先使用以下命令安装为用户级工具：
   uv tool install "git+https://github.com/tiny-paris/BIT101-mcp.git"
4. 识别我当前使用的 MCP 客户端，将 bit101-mcp 配置为用户级/全局 stdio MCP，
   名称使用 bit101，单次工具执行超时至少设置为 360 秒。
5. 如果找不到命令，运行 uv tool dir --bin，并在 MCP 配置中使用
   bit101-mcp（Windows 为 bit101-mcp.exe）的绝对路径。
6. 重启或重新加载 MCP，验证服务器已连接并能列出工具。
7. 不要在聊天、命令行参数、配置文件或环境变量中向我索要或写入账号、密码、
   短信验证码、Cookie、token 或乐学订阅 URL。需要认证时，只让我在 MCP 自动打开的
   127.0.0.1 临时页面中操作。
8. 不要修改默认上游地址。完成后告诉我修改了哪些配置文件以及验证结果。

Agent 完成安装后，直接在新对话中询问“总结今天的 BIT101 帖子”即可触发首次按需认证。

从源码安装

仓库公开后可以运行：

git clone https://github.com/tiny-paris/BIT101-mcp.git
cd BIT101-mcp
uv sync --all-groups
uv tool install .

uv tool install . 会把 bit101-mcp 安装为用户级命令。可以用下面的命令查看 uv 的可执行文件目录：

uv tool dir --bin

如果 MCP 客户端找不到 bit101-mcp，请重启客户端，或者在配置中使用该目录下 bit101-mcp.exe 的绝对路径。

仅在源码目录内运行

开发或测试时也可以不安装命令：

uv sync --all-groups
uv run bit101-mcp

stdio MCP 正常启动后会安静等待协议消息，看起来像“卡住”是正常的。不要把它当成普通交互式命令使用，也不要向它的终端输入账号密码。

依赖说明

项目声明了 7 个运行时直接依赖。它们不全是“MCP 协议强制要求”，而是当前完整功能各自需要的组件：

因此，对当前单包版本而言，这 7 个都是运行依赖；但从功能上看，icalendar 和 python-dateutil 只服务于乐学，未来如果拆成可选功能，可以改为额外依赖。现在拆分会增加安装和报错复杂度，节省的体积也很有限。

uv.lock 中还会看到 anyio、httpcore、certifi 等间接依赖，它们由上述库自动带入，不是项目主动调用的顶层组件，不应单独手动安装或删除。

以下依赖只用于开发和发布，不会作为普通运行依赖安装：

配置 MCP 客户端

首次学校认证最长可能需要几分钟，因此建议将单次工具调用超时设置为 360 秒。配置完成后需要重启 MCP 客户端，使其启动新的服务进程。

Codex

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面端的 Codex 主机共享 config.toml 中的 MCP 配置。官方说明见 Codex MCP 文档。

先通过 CLI 添加：

codex mcp add bit101 -- bit101-mcp
codex mcp list

然后检查用户级 %USERPROFILE%\.codex\config.toml，并补充工具超时：

[mcp_servers.bit101]
command = "bit101-mcp"
tool_timeout_sec = 360

如果只希望在某个可信项目中启用，可以把相同配置放进该项目的 .codex/config.toml。用户级配置则可以在任意目录和新对话中使用。

如果命令不在 Codex 的 PATH 中，可以改成绝对路径：

[mcp_servers.bit101]
command = 'C:\path\to\bit101-mcp.exe'
tool_timeout_sec = 360

OpenCode

本项目已使用下面的传统 OpenCode 配置完成 Windows 实机测试。放在项目根目录的 opencode.json 只对该项目生效；若希望在任意目录使用，请放到用户级 ~/.config/opencode/opencode.json（Windows 通常对应 %USERPROFILE%\.config\opencode\opencode.json）。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bit101": {
      "type": "local",
      "command": ["bit101-mcp"],
      "enabled": true,
      "timeout": 360000
    }
  }
}

验证连接：

opencode mcp list

如果只能在源码目录启动，通常是因为配置使用了相对命令且没有全局安装。安装 bit101-mcp，或把 command 改为 .venv\Scripts\bit101-mcp.exe 的绝对路径即可。

OpenCode V2 的配置结构有所不同，服务位于 mcp.servers 下，执行超时位于 mcp.timeout.execution。请以 OpenCode MCP 官方文档 为准：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timeout": {
      "execution": 360000
    },
    "servers": {
      "bit101": {
        "type": "local",
        "command": ["bit101-mcp"]
      }
    }
  }
}

Cursor

根据 Cursor MCP 文档，全局配置放在 ~/.cursor/mcp.json，项目配置放在 .cursor/mcp.json：

{
  "mcpServers": {
    "bit101": {
      "command": "bit101-mcp",
      "args": []
    }
  }
}

保存后重启 Cursor，在 Agent 的可用工具列表中确认 bit101 已启用。

Claude Code

按照 Claude Code MCP 文档 添加用户级 stdio 服务：

claude mcp add --scope user bit101 -- bit101-mcp
claude mcp list

通用 stdio 配置

其他 MCP 客户端只需配置一个本地 stdio 进程：

{
  "command": "bit101-mcp",
  "args": []
}

不要把账号、密码、Cookie、令牌或乐学 URL 写进 MCP 配置、环境变量或工具参数。

开始使用

配置完成后直接在 Agent 对话中提问，不需要手动启动后台服务。例如：

BIT101 社区与课程

总结一下今天 BIT101 都有哪些帖子。
查找最近关于“数据结构”的讨论。
如何评价某某老师的某门课？请区分普遍评价和少数意见。
查找“特立自动化”相关讨论，并列出信息来源。

课表与成绩

我今天有什么课？
我下周有什么课？按实际日期和开始时间排序。
列出本学期完整课表。
列出我的所有成绩，包括课程、学期、学分、成绩、班级平均分和最高分。

询问“本周/下周”时，服务器会根据当前日期计算精确周次，并返回 starts_at、ends_at 等完整时间；Agent 不需要自行猜测教学周或节次时间。

乐学

未来 14 天有哪些乐学任务？按截止时间排序。
看看未来 30 天的乐学日历。

可用工具

成功结果统一为：

{
  "ok": true,
  "data": {}
}

失败结果不会包含上游堆栈或认证信息：

{
  "ok": false,
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "service": "bit101",
    "message": "BIT101 is temporarily unavailable.",
    "retryable": true
  }
}

技术原理

核心分为四层：

1. MCP 工具层：只暴露帖子、课程、课表、成绩和任务等用户概念，不暴露 Cookie、挑战令牌或内部服务标识。

2. 客户端层：分别处理 BIT101 API 与学校数据网关，请求失败时判断会话是否过期，并只进行一次可恢复重试。

3. 标准化层：把不同上游格式转换成稳定、JSON 友好的字段；负责上海时区日期、教学周、课程时间、成绩和 ICS 事件解析。

4. 认证与存储层：需要时才打开本地页面；密码不进入 MCP 参数，成功后只保存可复用会话。

MCP 使用 stdio transport。标准输出只发送 MCP 协议数据，运行日志只写入标准错误，避免日志破坏协议通信。

认证流程

为什么浏览器中的 BIT101 登录不能直接复用？

浏览器 Cookie 属于浏览器自己的安全空间，MCP 是独立的本地进程。项目故意不读取 Chrome/Edge 的 Cookie 数据库，也不要求安装浏览器扩展。这样会多一次首次认证，但可以避免 MCP 扫描用户全部浏览器凭据。

新开一个 Agent 对话本身不会清除登录状态。MCP 启动时会读取并验证已保存的会话；只有会话不存在、上游判定失效、认证网关的临时挑战已过期，或者系统凭据存储不可用时才会重新登录。

BIT101

首次调用社区工具时：

1. MCP 在 127.0.0.1 的随机端口启动临时页面。

2. 用户在本地页面输入学号和 BIT101 密码。

3. 本地进程按现有 BIT101 登录协议处理密码，并通过 HTTPS 请求 BIT101 API。

4. 登录成功后，只把返回的 BIT101 会话保存到系统凭据管理器；原始密码不持久化。

5. 临时页面关闭，原来的工具调用继续执行。

学校课表与成绩

课表和成绩来自学校个人数据能力，与 BIT101 社区会话不是同一把“钥匙”。首次调用时，本地页面会收集统一认证账号、密码，以及需要时的短信验证码，并通过 HTTPS 交给现有 BIT-Login REST 网关。MCP 保存的是网关返回的短期挑战会话，不保存学校密码。

乐学日历

当前 BIT-Login REST 网关没有提供可供本项目调用的乐学日历接口，项目也不重新实现学校 CAS/SSO。因此 MVP 需要用户在乐学的 日历 → 导出日历 页面生成私人订阅地址，并在本地连接页粘贴一次。

连接页会实际下载并验证 iCalendar 内容，只有有效订阅才显示 Connected；普通 calendar/view.php 页面会被拒绝。订阅地址不进入 Agent 或 MCP 工具结果，并保存到系统凭据管理器。没有近期事件的有效日历会返回空列表。

认证、安全与隐私

先说结论

本项目降低了密码进入 Agent、聊天记录和日志的风险，但不能承诺“零风险”。安装本地 MCP 相当于安装一个能联网的本地程序；使用者需要信任项目源码、安装包、依赖项和配置的远程认证服务。

特别需要区分两句话：

• 密码不会发送给 Agent/LLM：是本项目明确实现的边界。

• 密码只在本机存在：不是。学校统一认证密码必须由本地 MCP 通过 HTTPS 提交给配置的远程 BIT-Login 网关完成认证。

哪些信息会去哪里？

默认上游地址为：

• BIT101 API：https://bit101.flwfdd.xyz

• BIT-Login REST：https://login.bit101.flwfdd.xyz

HTTPS 可以防止一般的网络窃听，但不能替代对服务器运营方的信任。介意学校密码经过远程网关的用户不应启用课表和成绩工具。

已实施的防护

• 临时 HTTP 服务只绑定 127.0.0.1，使用操作系统分配的随机端口。

• 每次认证使用 256 位随机 state，并进行恒定时间比较以抵御伪造提交。

• 页面禁用缓存、外部内容、iframe、referrer 和 MIME 猜测。

• 页面在成功、取消或超时后停止监听。

• 密码、验证码不写入文件；代码会在请求后尽快清除相关变量引用。

• 会话通过 Python keyring 写入操作系统凭据库（Windows Credential Manager，或 Linux 的 Secret Service/keyring 后端）；不可用时只在当前进程内存中保存，不回退到明文文件。

• 日志对密码、验证码、Cookie、Bearer token 和 Authorization 头进行脱敏。

• 乐学地址必须使用 bit.edu.cn 域名下的 HTTPS，并且必须返回有效 iCalendar。

• 工具均标记为只读，不提供修改学校或社区数据的能力。

使用者应当注意

• 只从可信仓库或可信发布页安装，并尽可能检查源码和发布哈希。

• 本地认证页地址应以 http://127.0.0.1:<随机端口>/connect 开头。

• 永远不要在 Agent 聊天框、MCP 参数、Issue 或日志中发送密码、验证码、Cookie、token 或乐学 URL。

• 不要在不受信任的公共电脑上使用个人学校账号。

• 乐学订阅 URL 是“拿到即可读取”的私人链接，应像密码一样保护；怀疑泄露时应在乐学重新生成。

• 查询成绩、课表时，相应数据会提供给当前 Agent。请根据所用模型和客户端的数据政策自行判断是否启用。

清除本地会话

在 Windows 中打开 控制面板 → 凭据管理器 → Windows 凭据；在 Linux 中打开当前桌面环境使用的 Secret Service 管理工具（常见为 GNOME Keyring 或 KDE Wallet）。删除服务名为 bit101-mcp 的以下条目：

• bit101-session

• school-session

• lexue-calendar-url

删除后，下一次调用对应工具会重新认证。卸载 Python 包不会自动删除这些系统凭据。若 Linux 没有可用的 keyring 后端，会话只保存在当前进程内存中，重启 MCP 后需要重新登录。

配置项

只允许通过环境变量配置非秘密参数：

凭据和会话不能通过工具参数或环境变量配置。修改上游地址意味着信任新的服务运营方，请谨慎使用。

常见问题

必须在项目目录启动 Agent 吗？

不必须。使用 uv tool install . 安装命令，并把 MCP 写入客户端的用户级配置后，可以从任意目录使用。项目根目录中的 opencode.json、.cursor/mcp.json 或 .codex/config.toml 只对对应项目生效。

为什么第一次使用会打开浏览器？

认证是按需触发的。第一次查询帖子会需要 BIT101 会话；第一次查询课表/成绩会需要学校会话；第一次查询乐学还需要私人日历订阅。密码和订阅地址不能经过聊天，所以使用临时本地页面收集。

为什么 BIT101 网页已经登录，MCP 仍然要求登录？

网页会话保存在浏览器 Cookie 中。MCP 不读取浏览器 Cookie，因此需要建立自己的最小会话。这样牺牲了一次首次登录便利性，但避免了直接访问浏览器全部登录数据。

为什么新对话偶尔还要重新登录？

新对话不会主动清除会话，但 MCP 会验证上游会话。会话过期、被服务器撤销、认证网关挑战失效，或者系统凭据存储不可用时会再次登录。若刚成功登录并立即重启就再次提示，请检查系统凭据库中是否存在 bit101-mcp 条目。

乐学显示 Connected，为什么没有任务？

如果订阅地址通过 iCalendar 验证，那么空列表通常只是选定时间范围内确实没有事件。可以把查询范围从 7 天扩大到 30 天确认。

为什么学校工具看起来很慢？

首次学校认证、短信验证和成绩明细获取可能耗时较长。请把 MCP 工具超时设置为 360 秒，并等待当前调用完成；不要同时重试多个学校工具。

bit101-mcp 命令找不到怎么办？

运行 uv tool dir --bin 找到安装目录，将它加入 PATH，或直接在 MCP 配置里填写 bit101-mcp.exe 的绝对路径。修改后重启客户端。

错误代码

所有错误都会经过清洗，不返回密码、Cookie、token、Authorization 头、原始堆栈或完整敏感请求。

开发

项目结构：

src/bit101_mcp/
├── server.py           # MCP 入口、工具注册和服务器说明
├── tools/              # Agent 可见的只读工具
├── clients/            # BIT101 与学校上游客户端
├── auth/               # 本地浏览器认证、状态机和凭据存储
├── models/             # 数据标准化、周次和 ICS 解析
└── logging_utils.py    # stderr 日志和秘密脱敏

安装开发依赖并运行检查：

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv build

维护者在发布前使用不随公共仓库分发的模拟测试验证数据标准化、认证状态、秘密脱敏和重试流程；这些测试不需要真实账号。真实账户集成测试保持手动、可选，不应把测试凭据提交到仓库或 CI。

致谢

感谢 BIT101 项目及其所有贡献者。学长学姐们长期维护的社区、课程评价、校园数据接口和认证工具，为同学们的校园生活带来了很大便利，也为本项目提供了重要基础。

本项目特别参考或使用了以下项目提供的接口与文档：

• BIT101

• BIT101-GO

• BIT101-Android

• BIT-Login

BIT101 MCP 是独立开发的非官方 MCP 客户端，通过网络接口与相关服务交互。本仓库的 MIT License 仅适用于本项目原创代码，不替代或变更任何上游项目的许可证。

当前限制

• Windows 已完成主要流程实机测试；Fedora 43 + niri 已验证可运行，其他 Linux 桌面环境尚未逐一验证。

• 乐学仍需手动粘贴一次导出的私人日历订阅地址。

• 学校会话由上游网关决定有效期，不能保证长期免登录。

• 成绩平均分和最高分取决于上游是否提供每门课的明细。

• 暂未发布 PyPI 包和 Windows 独立可执行文件。

• 不提供任何写操作。

许可证

本项目采用 MIT License。欢迎在保留版权与许可声明的前提下使用、修改、分发和提交改进。

贡献

欢迎提交 Issue 和 Pull Request。报告问题时请提供：

• 操作系统、Python、uv 和 MCP 客户端版本

• 使用的工具名称与经过脱敏的错误代码

• 是否出现本地认证页面

• 可复现步骤

请勿提交学号、密码、验证码、Cookie、token、完整请求头、乐学 URL 或其他个人信息。