BIT101 MCP

A local, read-only Model Context Protocol (MCP) service for Beijing Institute of Technology students. It converts BIT101 community content, course reviews, personal schedules, grades, and Lexue calendar into structured data that agents can easily understand, letting you ask questions directly in natural language.

[!IMPORTANT] This project is an unofficial community project and is not affiliated with Beijing Institute of Technology or the official BIT101. Windows has been tested on real hardware for the main workflows; Fedora 43 + niri has been verified to run; the project is still at the MVP stage. Please read Authentication, Security, and Privacy before use.

What It Can Do

• Summarize today's BIT101 posts, or search historical discussions by keyword

• Look up courses, instructors, and student reviews from past years

• Get today's, this week's, next week's, or a specified semester's schedule

• Query grades, credits, class averages, and highest scores (when provided upstream)

• Query Lexue calendar events for an upcoming period

• Combine data from different sources to answer questions, such as "What do people think of the instructors for my courses next semester?"

All tools are read-only. The project cannot post, like, comment, submit assignments, change grades, or modify any school data.

Related MCP server: MCP-Server-CollageAI

Live Demo

The following screenshots are from real calls on Windows using the OpenCode cli. The specific answers are generated by the model in use based on the data returned by MCP, do not represent the views of the project author, and may change as the model and data update.

Today's Post Summary

The agent calls list_today_posts to get the day's posts, then generates a brief summary based on titles, content, and engagement.

Instructor and Course Reviews

The agent first searches for the courses corresponding to the instructor, then calls get_course_reviews to aggregate course metadata, ratings, comments, and historical information.

Major Direction Discussion

When the course database has no exact match, the agent can continue searching BIT101 posts and read relevant discussions, demonstrating the effect of chaining multiple MCP tools together.

Lexue Calendar

The agent can query Lexue events within 7 to 90 days. A valid calendar with no upcoming tasks returns an empty list normally, rather than misjudging "no tasks" as an interface failure.

Prerequisites

Currently recommended environment:

• Windows 10/11, or Linux with a desktop browser and a usable system keyring (Fedora 43 + niri has been tested)

• Python 3.11 or higher

• uv

• A client supporting local stdio MCP, such as Codex, OpenCode, Cursor, or Claude Code

• A BIT101 account

• For querying schedules and grades, a Beijing Institute of Technology unified identity authentication account is also required; some logins may require SMS verification

• For querying Lexue, you need to export a private calendar subscription URL from Lexue once

Installation

Tell Your Agent (Recommended)

If your agent can execute terminal commands and modify its own MCP configuration, you can directly send the following text to it:

请帮我安装并配置 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. 不要修改默认上游地址。完成后告诉我修改了哪些配置文件以及验证结果。

After the agent completes the installation, simply ask "Summarize today's BIT101 posts" in a new conversation to trigger the first on-demand authentication.

Install from Source

Once the repository is public, you can run:

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

uv tool install . installs bit101-mcp as a user-level command. You can use the following command to view uv's executable directory:

uv tool dir --bin

If the MCP client cannot find bit101-mcp, restart the client, or use the absolute path of bit101-mcp.exe in that directory in the configuration.

Run Only Within the Source Directory

For development or testing, you can also run without installing:

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

After a stdio MCP starts normally, it quietly waits for protocol messages. It is normal for it to look "stuck." Do not treat it as an ordinary interactive command, and do not enter account credentials into its terminal.

[!NOTE] A simple uvx bit101-mcp will only be supported after the project is published to PyPI. The current README does not assume a PyPI package already exists.

Dependency Notes

The project declares 7 runtime direct dependencies. They are not all "mandated by the MCP protocol," but rather the components each currently needed for full functionality:

Therefore, for the current single-package version, all 7 are runtime dependencies; but from a functional standpoint, icalendar and python-dateutil only serve Lexue. If split into optional features in the future, they could become extra dependencies. Splitting them now would increase installation and error-reporting complexity, and the size savings would be very limited.

You will also see indirect dependencies such as anyio, httpcore, and certifi in uv.lock. They are pulled in automatically by the libraries above, are not top-level components actively called by the project, and should not be manually installed or removed on their own.

The following dependencies are only used for development and release, and will not be installed as ordinary runtime dependencies:

Configuring MCP Clients

The first school authentication can take up to a few minutes, so it is recommended to set the single tool call timeout to 360 seconds. After configuration, restart the MCP client so it starts a new service process.

Codex

The Codex CLI, Codex IDE extension, and the Codex host in the ChatGPT desktop app share the MCP configuration in config.toml. See the official Codex MCP documentation.

First add it via the CLI:

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

Then check the user-level %USERPROFILE%\.codex\config.toml and add the tool timeout:

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

If you only want to enable it in a specific trusted project, you can put the same configuration in that project's .codex/config.toml. The user-level configuration works in any directory and in new conversations.

If the command is not in Codex's PATH, you can change it to an absolute path:

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

OpenCode

This project has completed Windows real-hardware testing using the traditional OpenCode configuration below. Placing it in opencode.json at the project root only applies to that project; to use it in any directory, place it in the user-level ~/.config/opencode/opencode.json (on Windows this usually corresponds to %USERPROFILE%\.config\opencode\opencode.json).

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

Verify the connection:

opencode mcp list

If it can only start in the source directory, it is usually because the configuration uses a relative command and there is no global installation. Install bit101-mcp, or change command to the absolute path of .venv\Scripts\bit101-mcp.exe.

OpenCode V2 has a different configuration structure: services are under mcp.servers and the execution timeout is under mcp.timeout.execution. Please refer to the official OpenCode MCP documentation:

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

Cursor

According to the Cursor MCP documentation, global configuration goes in ~/.cursor/mcp.json and project configuration goes in .cursor/mcp.json:

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

After saving, restart Cursor and confirm that bit101 is enabled in the agent's available tools list.

Claude Code

Following the Claude Code MCP documentation, add a user-level stdio service:

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

Generic stdio Configuration

Other MCP clients only need to configure a local stdio process:

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

Do not put account names, passwords, cookies, tokens, or Lexue URLs into MCP configuration, environment variables, or tool parameters.

Getting Started

After configuration, just ask questions directly in the agent conversation. No need to manually start a background service. For example:

BIT101 Community and Courses

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

Schedule and Grades

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

When asking about "this week/next week," the server calculates the exact week based on the current date and returns complete times such as starts_at and ends_at; the agent does not need to guess teaching weeks or period times on its own.

Lexue

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

Available Tools

Successful results are uniformly formatted as:

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

Failed results do not include upstream stack traces or authentication information:

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

Technical Architecture

The core is divided into four layers:

1. MCP tool layer: Only exposes user-facing concepts such as posts, courses, schedules, grades, and tasks; never exposes cookies, challenge tokens, or internal service identifiers.

2. Client layer: Handles the BIT101 API and the school data gateway separately; on request failure, determines whether the session has expired and performs only one recoverable retry.

3. Normalization layer: Converts different upstream formats into stable, JSON-friendly fields; handles Shanghai timezone dates, teaching weeks, course times, grades, and ICS event parsing.

4. Authentication and storage layer: Opens a local page only when needed; passwords never enter MCP parameters; only reusable sessions are saved after success.

MCP uses the stdio transport. Standard output only carries MCP protocol data; runtime logs are written only to standard error, preventing logs from corrupting protocol communication.

Authentication Flow

Why can't the browser's BIT101 login be reused directly?

Browser cookies belong to the browser's own security space, and MCP is an independent local process. The project deliberately does not read Chrome/Edge cookie databases and does not require installing a browser extension. This adds one extra initial authentication, but avoids MCP scanning all of the user's browser credentials.

Opening a new agent conversation does not by itself clear the login state. MCP reads and validates the saved session at startup; it only re-authenticates when the session does not exist, the upstream determines it is invalid, the authentication gateway's temporary challenge has expired, or the system credential store is unavailable.

BIT101

On the first call to a community tool:

1. MCP starts a temporary page on a random port at 127.0.0.1.

2. The user enters their student ID and BIT101 password on the local page.

3. The local process handles the password according to the existing BIT101 login protocol and requests the BIT101 API over HTTPS.

4. After successful login, only the returned BIT101 session is saved to the system credential manager; the raw password is not persisted.

5. The temporary page closes, and the original tool call continues.

School Schedule and Grades

Schedules and grades come from the school's personal data capability and are not the same "key" as the BIT101 community session. On the first call, the local page collects the unified authentication account, password, and an SMS verification code when needed, and submits them over HTTPS to the existing BIT-Login REST gateway. MCP saves the short-term challenge session returned by the gateway, not the school password.

Lexue Calendar

The current BIT-Login REST gateway does not provide a Lexue calendar interface that this project can call, and the project does not reimplement the school's CAS/SSO. Therefore, the MVP requires the user to generate a private subscription URL on the Lexue Calendar → Export Calendar page and paste it once on the local connection page.

The connection page actually downloads and validates the iCalendar content; only a valid subscription shows Connected. Ordinary calendar/view.php pages are rejected. The subscription URL does not enter the agent or MCP tool results and is saved to the system credential manager. A valid calendar with no upcoming events returns an empty list.

Authentication, Security, and Privacy

Bottom Line First

This project reduces the risk of passwords entering the agent, chat history, and logs, but cannot promise "zero risk." Installing a local MCP is equivalent to installing a local program that can access the network; users need to trust the project source code, installation packages, dependencies, and the configured remote authentication services.

Two statements in particular need to be distinguished:

• Passwords are not sent to the agent/LLM: this is an explicit boundary implemented by this project.

• Passwords only exist on this machine: no. The school unified authentication password must be submitted by the local MCP over HTTPS to the configured remote BIT-Login gateway to complete authentication.

What Information Goes Where?

Default upstream addresses:

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

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

HTTPS prevents ordinary network eavesdropping but does not replace trust in the server operator. Users who are uncomfortable with their school password passing through a remote gateway should not enable the schedule and grade tools.

Implemented Protections

• The temporary HTTP service only binds to 127.0.0.1 and uses a random port assigned by the operating system.

• Each authentication uses a 256-bit random state and constant-time comparison to resist forged submissions.

• The page disables caching, external content, iframes, referrers, and MIME sniffing.

• The page stops listening after success, cancellation, or timeout.

• Passwords and verification codes are not written to files; the code clears relevant variable references as soon as possible after the request.

• Sessions are written to the OS credential store via Python keyring (Windows Credential Manager, or the Secret Service/keyring backend on Linux); when unavailable, they are only kept in the current process memory, with no fallback to plaintext files.

• Logs redact passwords, verification codes, cookies, Bearer tokens, and Authorization headers.

• The Lexue URL must use HTTPS under the bit.edu.cn domain and must return valid iCalendar.

• All tools are marked read-only and provide no ability to modify school or community data.

What Users Should Note

• Only install from trusted repositories or trusted release pages, and check the source code and release hashes where possible.

• The local authentication page address should start with http://127.0.0.1:<random port>/connect.

• Never send passwords, verification codes, cookies, tokens, or Lexue URLs in the agent chat box, MCP parameters, issues, or logs.

• Do not use personal school accounts on untrusted public computers.

• The Lexue subscription URL is a private link that grants read access as soon as it is obtained; protect it like a password, and regenerate it in Lexue if you suspect it has leaked.

• When querying grades or schedules, the corresponding data is provided to the current agent. Decide whether to enable these tools based on the data policies of the model and client you use.

Clearing Local Sessions

On Windows, open Control Panel → Credential Manager → Windows Credentials; on Linux, open the Secret Service management tool used by the current desktop environment (commonly GNOME Keyring or KDE Wallet). Delete the following entries with the service name bit101-mcp:

• bit101-session

• school-session

• lexue-calendar-url

After deletion, the next call to the corresponding tool will re-authenticate. Uninstalling the Python package does not automatically delete these system credentials. If Linux has no available keyring backend, sessions are only kept in the current process memory and you will need to log in again after restarting MCP.

Configuration Options

Only non-secret parameters can be configured via environment variables:

Credentials and sessions cannot be configured via tool parameters or environment variables. Changing the upstream address means trusting a new service operator; use with caution.

FAQ

Do I have to start the agent in the project directory?

No. After installing the command with uv tool install . and writing the MCP into the client's user-level configuration, you can use it from any directory. The opencode.json, .cursor/mcp.json, or .codex/config.toml in the project root only apply to that project.

Why does the browser open on first use?

Authentication is triggered on demand. The first post query needs a BIT101 session; the first schedule/grade query needs a school session; the first Lexue query also needs a private calendar subscription. Passwords and subscription URLs cannot go through the chat, so a temporary local page is used to collect them.

Why does MCP still require login when the BIT101 webpage is already logged in?

The webpage session is stored in browser cookies. MCP does not read browser cookies, so it needs to establish its own minimal session. This sacrifices one initial login convenience but avoids directly accessing all of the browser's login data.

Why do I occasionally need to log in again in a new conversation?

A new conversation does not proactively clear sessions, but MCP validates the upstream session. It will log in again when the session expires, is revoked by the server, the authentication gateway challenge becomes invalid, or the system credential store is unavailable. If you are prompted again immediately after a successful login and restart, check whether a bit101-mcp entry exists in the system credential store.

Lexue shows Connected, but why are there no tasks?

If the subscription URL passes iCalendar validation, an empty list usually just means there are genuinely no events in the selected time range. You can expand the query range from 7 days to 30 days to confirm.

Why do the school tools seem slow?

The first school authentication, SMS verification, and grade detail retrieval can take a while. Set the MCP tool timeout to 360 seconds and wait for the current call to finish; do not retry multiple school tools at the same time.

What if the bit101-mcp command cannot be found?

Run uv tool dir --bin to find the installation directory, add it to PATH, or directly fill in the absolute path of bit101-mcp.exe in the MCP configuration. Restart the client after making changes.

Error Codes

All errors are sanitized and do not return passwords, cookies, tokens, Authorization headers, raw stack traces, or complete sensitive requests.

Development

Project structure:

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

Install development dependencies and run checks:

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

Before release, maintainers use mock tests that are not distributed with the public repository to verify data normalization, authentication state, secret redaction, and retry flows; these tests do not require real accounts. Real-account integration testing remains manual and optional, and test credentials should not be committed to the repository or CI.

Acknowledgments

Thanks to the BIT101 project and all its contributors. The community, course reviews, campus data interfaces, and authentication tools that seniors have maintained over the years have brought great convenience to students' campus life and also provided an important foundation for this project.

This project specifically references or uses interfaces and documentation from the following projects:

• BIT101

• BIT101-GO

• BIT101-Android

• BIT-Login

BIT101 MCP is an independently developed unofficial MCP client that interacts with related services through network interfaces. The MIT License in this repository applies only to this project's original code and does not replace or alter the licenses of any upstream projects.

Current Limitations

• Windows has been tested on real hardware for the main workflows; Fedora 43 + niri has been verified to run, but other Linux desktop environments have not been individually verified.

• Lexue still requires manually pasting an exported private calendar subscription URL once.

• The school session validity is determined by the upstream gateway and long-term login-free access cannot be guaranteed.

• Grade averages and highest scores depend on whether the upstream provides per-course details.

• PyPI packages and standalone Windows executables have not yet been released.

• No write operations are provided.

License

This project is licensed under the MIT License. You are welcome to use, modify, distribute, and submit improvements, provided that the copyright and license notices are retained.

Contributing

We welcome Issues and Pull Requests. When reporting a problem, please provide:

• Operating system, Python, uv, and MCP client versions

• The tool name used and the sanitized error code

• Whether a local authentication page appears

• Reproducible steps

Do not submit student IDs, passwords, verification codes, cookies, tokens, full request headers, 乐学 URLs, or other personal information.