内容
# 智慧校园 MCP 服务器
<!-- mcp-name: io.github.MauroDruwel/smartschool-mcp -->
[](https://github.com/MauroDruwel/Smartschool-MCP/actions/workflows/ci.yml)
[](https://codecov.io/gh/MauroDruwel/Smartschool-MCP)
[](https://pypi.org/project/smartschool-mcp/)
[](LICENSE)
[](https://www.python.org/downloads/)
连接 Claude（和其他 MCP 客户端）到您的智慧校园账户 — 用简单语言询问成绩、作业、消息和日程安排。
## 工具
| 工具 | 功能 |
|------|-------------|
| `get_courses` | 列出已注册课程及教师信息 |
| `get_results` | 成绩查询，支持筛选、分页和统计 |
| `get_future_tasks` | 按日期组织的即将到来的作业 |
| `get_messages` | 收件箱/已发送/回收站，支持搜索、发件人筛选和正文检索 |
| `get_schedule` | 按偏移量查询日程（0 = 今天，1 = 明天，…） |
| `get_periods` | 当前学年的学术术语 |
| `get_reports` | 可用的成绩单 |
| `get_planned_elements` | 未来 N 天的计划事项 |
| `get_student_support_links` | 学校支持资源和链接 |
| `get_attachments` | 查询特定消息的附件列表 |
| `download_attachment` | 下载特定附件（按消息和文件 ID） |
## 快速入门 — Claude 桌面版
```bash
uvx mcp install smartschool-mcp \
-e SMARTSCHOOL_USERNAME="您" \
-e SMARTSCHOOL_PASSWORD="秘密" \
-e SMARTSCHOOL_MAIN_URL="school.smartschool.be" \
-e SMARTSCHOOL_MFA="YYYY-MM-DD"
```
或手动添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"smartschool": {
"command": "uvx",
"args": ["smartschool-mcp"],
"env": {
"SMARTSCHOOL_USERNAME": "您",
"SMARTSCHOOL_PASSWORD": "秘密",
"SMARTSCHOOL_MAIN_URL": "school.smartschool.be",
"SMARTSCHOOL_MFA": "YYYY-MM-DD"
}
}
}
}
```
配置文件位置：`%APPDATA%\Claude\claude_desktop_config.json`（Windows）· `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）· `~/.config/Claude/claude_desktop_config.json`（Linux）
## 远程 / claude.ai
服务器支持 **Streamable HTTP** 传输协议，用于在 claude.ai 上作为远程集成使用。
### 单用户模式
一个服务器实例，您的凭证存储在环境变量中：
```bash
export SMARTSCHOOL_USERNAME="..."
export SMARTSCHOOL_PASSWORD="..."
export SMARTSCHOOL_MAIN_URL="school.smartschool.be"
export SMARTSCHOOL_MFA="YYYY-MM-DD"
export MCP_API_KEY="a-long-random-secret" # 可选但推荐
smartschool-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
添加到 claude.ai → 设置 → 集成：
- **网址：** `https://your-domain.example.com/mcp`
- **授权头：** `Bearer <your MCP_API_KEY>` （如果设置）
### 通用模式
一个托管的服务器实例为 **任何** 智慧校园用户提供服务 — 无需逐一部署。
```bash
smartschool-mcp --transport streamable-http --universal --host 0.0.0.0 --port 8000
```
凭证在每个请求中传递：
| 内容 | 位置 | 示例 |
|------|-------|---------|
| 学校网址 | URL 查询参数 `school` | `?school=myschool.smartschool.be` |
| 出生日期（MFA） | URL 查询参数 `mfa` | `&mfa=2000-01-15` |
| 用户名 | OAuth 客户端 ID | 您的智慧校园用户名 |
| 密码 | OAuth 客户端密钥 | 您的智慧校园密码 |
在 claude.ai → 设置 → 集成 → 添加自定义连接器：
- **网址：** `https://your-domain.example.com/mcp?school=myschool.smartschool.be&mfa=YYYY-MM-DD`
- **OAuth 客户端 ID：** 您的智慧校园用户名
- **OAuth 客户端密钥：** 您的智慧校园密码
> **MFA** 是您的出生日期，格式为 `YYYY-MM-DD`。如果您的账户不需要 MFA，请省略 `mfa` 参数。
### 使服务器可公开访问
Claude.ai 需要 HTTPS。一些选项：
| 选项 | 命令 |
|--------|---------|
| Cloudflare 隧道 | `cloudflared tunnel --url http://localhost:8000` |
| ngrok | `ngrok http 8000` |
| 虚拟专用服务器 | nginx / Caddy，搭配 Let's Encrypt 证书 |
## 环境变量
| 变量 | CLI 标志 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `MCP_TRANSPORT` | `--transport` | `stdio` | `stdio` 或 `streamable-http` |
| `MCP_HOST` | `--host` | `0.0.0.0` | 绑定地址（仅 HTTP） |
| `MCP_PORT` | `--port` | `8000` | 端口（仅 HTTP） |
| `MCP_API_KEY` | — | — | 静态 Bearer 令牌（单用户模式） |
| `MCP_UNIVERSAL` | `--universal` | 关闭 | 启用通用模式（设置为 `1`、`true` 或 `yes`） |
| `SESSION_TTL_SECONDS` | — | `3600` | 会话缓存时间（通用模式） |
| `SMARTSCHOOL_USERNAME` | — | — | 您的智慧校园用户名 |
| `SMARTSCHOOL_PASSWORD` | — | — | 您的智慧校园密码 |
| `SMARTSCHOOL_MAIN_URL` | — | — | 学校主机名，例如 `school.smartschool.be` |
| `SMARTSCHOOL_MFA` | — | — | 出生日期 `YYYY-MM-DD`（如果需要） |
## 贡献
欢迎提交拉取请求。运行 `uv sync --extra dev` 安装开发依赖，然后运行 `uv run pytest` / `uv run ruff check .` / `uv run mypy smartschool_mcp/` 然后提交。
## 免责声明
非官方工具，与智慧校园无关联。请根据学校的服务条款使用。
