Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@campus-edu-mcp 查一下我明天的课表"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
只读的高校教务 MCP 服务：让 AI 回答「我明天几点上课」「下周有什么考试」「上学期挂科了吗」。 非官方项目，只能查询你本人的账号，永远不做选课、退课、评教等任何写操作。
当前版本 v1.0.0（本地，未发布）。API 稳定性与弃用策略见 docs/api-stability.md，从 0.1.0 升级见 docs/migration.md。默认适配强智教务（jsxsd）；正方 V9 适配器仍保留但未实测。
示例学校配置见 schools/example-qiangzhi.yaml（请改成你自己学校的 base_url）。
强智适配器已在一所强智校做过只读 live 验证（课表 / 成绩，2026-10-16）；考试路径因校而异，有实际考试数据时的解析尚未验证。正方 V9 未做 live 实测。
厂商用 --vendor qiangzhi|zfsoft_v9 选择（默认 qiangzhi）。
MCP 工具 | 说明 |
| 本人课表 |
| 本人考试安排（时间、地点、座位号） |
| 成绩。默认只返回课程、学分、课程性质、是否通过； |
| 列出教务系统可选学期（已在一所强智校只读实测） |
| 某教学周某天的空闲教室（只读查询教室占用网格，不会提交借用申请；已在一所强智校只读实测） |
| 会话是否已导入、是否仍有效（不返回任何 Cookie） |
year 是学年起始年（2025 表示 2025-2026 学年），term 为 1/2/3，不填则按日期推断当前学期。
每个数据工具结果带 meta（status: verified / stale / pending）。正方 V9 默认禁用，需 CAMPUS_EDU_ALLOW_UNVERIFIED=1。实验性登录（未经 live 实测，仅强智、仅 CLI）：campus-edu-mcp login --username 学号，验证码图片保存在本地由你肉眼输入，密码只在终端 getpass 输入、不保存、不经过 MCP；需要系统 keyring。失败时请继续用 import-session。学校登记表：campus-edu-mcp schools（last_verified 超过 183 天显示 stale）。实验性 Streamable HTTP：CAMPUS_EDU_HTTP_TOKEN=<≥32 位随机串> campus-edu-mcp serve --transport http --port 8848，只监听 127.0.0.1，每个请求需 Authorization: Bearer <token>，Host/Origin 仅限本机。自检：campus-edu-mcp doctor [--online]（只报告有/无，不输出 Cookie）。实验性 CLI：campus-edu-mcp export-ics --term-start YYYY-MM-DD --periods 作息.json --out kb.ics（作息时间需自己提供；时间为不带时区的本地时间）。
课表 / 考试 / 成绩结果都不含学号、姓名、排名，并附带 privacy_notice（session_status 不含该字段）。
Related MCP server: UofT Student Helper MCP Server
stdio 只说明 MCP 服务和客户端在本机通信。如果你的 AI 客户端用的是云端模型（Codex、ChatGPT、Claude 等），
工具返回的课表、成绩会作为对话内容发送给模型服务商。 本项目无法阻止这一点，只能尽量少返回数据。
请自行评估后再使用 get_grades(include_scores=true)。
需要 Python ≥ 3.11 和 uv。
git clone <repo-url> campus-edu-mcp # 目前仓库只在本地，可直接解压源码包
cd campus-edu-mcp
uv sync
# 1. 配置教务地址（换成你学校的）
uv run campus-edu-mcp configure --base-url https://jw.example.edu.cn/jsxsd/ --vendor qiangzhi --school example-qiangzhi
# 2. 在浏览器里登录教务系统，按 F12 → 网络 → 任一请求 → 复制 Cookie 请求头，
# 保存为 cookie.txt（也支持 cookies.txt 和浏览器扩展导出的 JSON）
uv run campus-edu-mcp import-session --cookie-file .\cookie.txt
Remove-Item .\cookie.txt # 已加密保存，原文件可以删掉
# 3. 检查会话
uv run campus-edu-mcp session-statusmacOS / Linux 命令相同，把路径写成 ./cookie.txt 即可。
{
"mcpServers": {
"campus-edu": {
"command": "uv",
"args": ["--directory", "C:\\path\\to\\campus-edu-mcp", "run", "campus-edu-mcp"]
}
}
}Codex CLI 可以用：codex mcp add campus-edu -- uv --directory C:\path\to\campus-edu-mcp run campus-edu-mcp
（命令格式以你所用 Codex 版本的文档为准）。仓库里的 SKILL.md 可作为 Skill 提供给 AI。
会话过期后，工具会提示重新导入；重复第 2 步即可。不要把 Cookie 发给 AI。
Windows：会话加密文件写在
%APPDATA%\campus-edu-mcp\。多用户共享同一 Windows 账号时，请自行评估本机权限；本项目不额外配置 NTFS ACL。
uv run python -m mock_server --port 8765 # 终端 1：默认虚构强智 jsxsd
# 终端 2
uv run campus-edu-mcp configure --base-url http://127.0.0.1:8765/jsxsd/ --vendor qiangzhi --min-interval 0
Set-Content mock-cookie.txt "JSESSIONID=FAKE-MOCK-SESSION"
uv run campus-edu-mcp import-session --cookie-file .\mock-cookie.txt
uv run campus-edu-mcp session-status只读守卫（guard.py）在 httpx transport 层检查每个出站请求：方法 + 路径 + 参数白名单，
固定参数（如 doType=query、gnmkdm）必须精确匹配，其余参数要匹配正则，未登记的参数直接拒绝；
关闭自动重定向，每一跳重新检查，跳到登录页视为会话失效；默认每 2 秒最多 1 次请求。
静态检查（scripts/check_adapters.py）用 AST 禁止适配器自己联网。
Cookie 只能通过命令行导入，用 Fernet 加密，密钥存系统 keyring；keyring 不可用时不落盘，
改用环境变量 CAMPUS_EDU_COOKIE_FILE 指向 Cookie 文件（写在 MCP 客户端配置的 env 里）。
日志脱敏：Cookie、token、学号、URL 中的敏感参数统一打码。
不支持账号密码登录（计划 v0.2），不做任何验证码识别，不接入打码平台。
详见 docs/compliance.md 与 SECURITY.md。
见 .env.example：CAMPUS_EDU_BASE_URL、CAMPUS_EDU_COOKIE_FILE、CAMPUS_EDU_DATA_DIR、
CAMPUS_EDU_MIN_INTERVAL、CAMPUS_EDU_COOKIE（仅 import-session --from-env 使用）。
uv sync
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest # 整体覆盖率 ≥70%
uv run python scripts/check_core_coverage.py # 核心模块 ≥80%
uv run python scripts/check_adapters.py
uv run python scripts/check_fixtures.py贡献指南见 CONTRIBUTING.md，适配器规范见 docs/adapter-spec.md。 不接受抢课、选退课、评教代填等任何写操作相关的 PR。
本项目与任何学校、正方公司无关。仅供本人查询自己的数据、学习研究使用；自动化访问可能违反学校规定， 请自行确认，后果自负。学校提出要求时，我们会配合移除相关支持。
MIT
查询某教学周某天的空闲教室（只读，不会提交借用申请）。
week 为教学周（1-30），weekday 为 1=周一 … 7=周日；periods 为必须全部空闲的节次编码
（如 ["0102","0304"]，可选值见返回的 periods）；campus 为校区编号；
year/term 不填则用教务系统默认学期。
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | ||
| week | Yes | ||
| year | No | ||
| limit | No | ||
| campus | No | ||
| periods | No | ||
| weekday | Yes | ||
| min_capacity | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the burden is lighter, yet the description still adds real behavior: it will not create a borrowing request, and omitting year/term silently falls back to the academic system's default semester. No auth or rate-limit context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first clause and the parameter glosses are dense and non-repetitive. The parenthetical read-only note duplicates the annotation, and the indented multi-line layout is slightly loose, but nothing is wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation (the description rightly points to the returned periods for valid codes). It covers all required params and the main optional ones; only limit/min_capacity semantics are missing for an 8-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the load, and it does for most parameters: week range 1-30, weekday 1-7 mapping, periods as all-must-be-free codes with an example, campus as a campus code, and year/term defaulting. It leaves 'limit' and 'min_capacity' entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (query free classrooms for a given teaching week/day) with scope qualifiers, and the 'read-only, will not submit a borrowing request' clause immediately separates it from any booking sibling. An agent can tell what it returns without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames when to use it: read-only lookup, not an application submission, with the year/term defaulting rule spelled out. It never names an alternative sibling (e.g. get_timetable) to route against, so it stops short of the explicit when-not/alternatives bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询本人考试安排（时间、地点、座位号）。参数同 get_timetable。
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | ||
| year | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds one genuinely new behavioral fact — that results are scoped to '本人' (the authenticated user) — but says nothing about pagination or freshness, so it only modestly exceeds the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, both carrying load, with the purpose front-loaded before the parameter note. The cross-reference to get_timetable is efficient but leaves the definition non-self-contained.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be restated. However, for a zero-required-parameter tool whose parameters are 0% documented, the only guidance is an indirect pointer to a sibling, leaving the invocation semantics partially unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so term and year carry no meaning anywhere except the phrase '参数同 get_timetable', which forces the agent to open another tool's schema. The description does not explain accepted values, formats, or what happens when they are omitted (default null).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (查询本人考试安排) and enumerates what is returned (时间、地点、座位号), which cleanly separates it from get_timetable. An agent can identify the tool's domain without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The contrast with get_timetable is implied by the resource name (exams vs timetable) and the parameter deferral, but there is no explicit statement of when to use this tool versus get_timetable or other siblings. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询本人成绩。
默认返回课程、学分、课程性质、是否通过；include_scores=true 时才返回分数和绩点。
year 与 term 都不填则返回全部学期（结果中 term 为 null）。返回的数据会进入模型上下文。
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | ||
| year | No | ||
| include_scores | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: the default field set (course, credits, nature, pass status), the conditional expansion via include_scores, and the all-semesters fallback with term=null. The note that returned data enters the model context is a useful operational caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action, followed by the conditional field behavior and the unset-filter fallback. No filler or redundancy; structure is efficient though slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and the description covers filtering behavior and default vs. expanded fields adequately for a read-only query tool. An agent has enough to call it correctly, with only minor gaps in parameter format details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it fully explains include_scores=true behavior and the combined year/term default (both unset returns all terms). It stops short of giving expected formats or value ranges for year/term integers, so it isn't exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('查询本人成绩' – query one's own grades) with an explicit self-scope. It is immediately distinguishable from siblings like get_exams, get_timetable, and get_terms, which cover exams, schedule, and term lists respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (fetch the caller's grades), and the description clarifies default vs. score-inclusive behavior, but it never states when to prefer this tool over alternatives or any prerequisites. No explicit when-to-use/when-not guidance is given, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出教务系统可选的学期（current=true 为系统默认学期）。已在一所强智校只读实测。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond that: it states the tool was verified read-only against one Strongzhi deployment, which signals a reliability/coverage caveat an agent would otherwise lack.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no padding, with the core action front-loaded. The trailing verification note is meta-information but short and useful enough to justify its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be spelled out, and annotations cover the safety profile. For a zero-parameter read tool the description is sufficient, with only the vague current=true phrasing leaving a minor interpretive gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The mention of current=true refers to a response field identifying the default term rather than an input, which is a slightly ambiguous framing but harmless given the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it lists the selectable terms/semesters in the academic system. The resource is unambiguous and clearly distinct from siblings like get_timetable or get_grades, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied — an agent infers it should call this to discover valid term values (e.g., before querying grades or timetable). There is no explicit when-to-use or when-not-to-use guidance, nor any prerequisite call ordering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询本人课表。
year 为学年起始年（如 2025 表示 2025-2026 学年），term 为 1/2/3；不填则取当前学期。
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | ||
| year | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that the query is scoped to the caller's own timetable ('本人'), a useful access-scope detail, but says nothing about rate limits, auth requirements, or data freshness beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight lines: the purpose clause first, then the parameter semantics. No filler, no repetition of the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and both parameters are explained despite 0% schema coverage. The definition is nearly complete; only the individual term-value semantics remain slightly underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden, and it does so well: it defines year as the academic-year start (2025 = 2025-2026) and term as 1/2/3, plus the default-to-current-semester behavior. The only gap is that the meaning of the individual term values (e.g. what term 3 represents) is left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('查询本人课表' – query one's own timetable), which is cleanly distinguishable from sibling resources like get_exams and get_grades. It does not explicitly name or contrast with siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an implied usage cue by explaining that omitting year/term falls back to the current semester, which tells the agent when defaults are acceptable. However, it offers no explicit guidance on when to prefer this tool over alternatives such as get_terms or get_exams.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
检查教务会话是否已导入、是否仍然有效。不会返回任何 Cookie 内容。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real context beyond them by disclosing what the tool will NOT return (no Cookie contents), which is meaningful privacy/security information not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero padding, with the core check stated first and the security caveat second. Nothing is redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not required in the description, and the zero-parameter surface keeps complexity low. The only shortfall is the absence of guidance on how session validity relates to calling the sibling data tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% with an empty property set, and there is nothing parameter-related the description needs to or does clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete verb and resource: checks whether the academic-affairs session has been imported and whether it is still valid. This is clearly a session-state probe, distinct in kind from the data-fetching siblings, though it never explicitly names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied – an agent can infer this should be called to verify the session before invoking get_timetable/get_grades/etc. There is no explicit when-to-use, precondition, or statement of what to do if the check fails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_empty_classroomsget_examsget_gradesget_termsget_timetablesession_statusScored across 6 tools
Each tool targets a distinct resource (timetable, exams, grades, terms, session, empty classrooms) with no functional overlap. An agent can unambiguously pick the right tool for any academic query.
Five tools follow a consistent snake_case 'get_noun' pattern (get_timetable, get_exams, get_grades, get_terms, get_empty_classrooms). session_status breaks the verb pattern but remains readable and snake_case, a minor deviation.
Six tools is well-scoped for a read-only campus query server, with each tool earning its place covering a distinct informational need.
The read-only surface covers the core academic queries (schedule, exams, grades, terms, session, classrooms) well. Gaps are mostly write/action operations (e.g. course selection, applications) that are arguably out of scope for a read-only design.
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
Read-only access to Epivo's live course catalogue for AI agents.
Unofficial NTNU course data: search, timetables, grades, course info, and exam logistics.
Read-only AI access to Osboon business card analytics, viewers, links, connections and contacts.
