Smartschool MCP

🚀 智能校园MCP服务器

智能校园MCP服务器是一个模型上下文协议（MCP）服务器，它能让AI助手与智能校园平台进行交互，使AI助手能够访问课程、成绩、作业和消息等信息。

🚀 快速开始

智能校园MCP服务器允许像Claude这样的AI助手无缝地从智能校园平台访问和检索信息。智能校园是比利时和荷兰广泛使用的教育管理平台。借助这个MCP服务器，学生无需离开对话，就能向他们的AI助手询问成绩、即将到来的作业、课程信息和消息。

✨ 主要特性

智能校园MCP服务器提供以下工具：

📚 get_courses

检索所有可用课程及其教师信息。

• 列出所有已注册的课程
• 包含每门课程的教师姓名

📊 get_results

获取学生成绩和结果的详细信息。

• 支持使用limit和offset参数进行分页
• 可使用course_filter按课程名称进行过滤
• 可使用include_details参数获取可选的详细统计信息（平均分、中位数）
• 包含分数描述、日期和反馈

📝 get_future_tasks

获取按日期组织的即将到来的作业和任务。

• 显示所有未来的作业
• 按日期和课程组织
• 包含任务描述和标签

📧 get_messages

通过强大的过滤选项访问邮箱消息。

• 选择邮箱类型：INBOX、SENT、DRAFT等
• 使用search_query按内容搜索消息
• 使用sender_filter按发件人进行过滤
• 可使用include_body参数获取完整的消息正文
• 支持分页

📦 安装指南

前提条件

• Python 3.13 或更高版本
• uv 包管理器（推荐）或 pip
• 具有有效凭证的智能校园账户

使用MCP CLI快速安装（推荐）

安装和配置服务器的最简单方法是使用MCP CLI：

# 从PyPI安装并自动配置
uvx mcp install smartschool-mcp \
  -e SMARTSCHOOL_USERNAME="your_username" \
  -e SMARTSCHOOL_PASSWORD="your_password" \
  -e SMARTSCHOOL_MAIN_URL="your-school.smartschool.be" \
  -e SMARTSCHOOL_MFA="YYYY-MM-DD"

此命令将：

• 从PyPI安装包
• 将其添加到你的Claude桌面配置中
• 自动设置环境变量

从PyPI手动安装

如果你更喜欢手动安装并稍后配置：

# 使用pip
pip install smartschool-mcp

# 使用uv（推荐）
uv pip install smartschool-mcp

手动安装后，你需要手动配置Claude桌面（请参阅下面的配置部分）。

从源代码安装

如果你想贡献代码或使用最新的开发版本：

git clone https://github.com/MauroDruwel/Smartschool-MCP.git
cd Smartschool-MCP
uv sync

配置参数

💻 使用示例

安装并与Claude桌面或其他MCP客户端配置好后，你可以提出如下问题：

• "我最近的成绩如何？"
• "给我看看我即将到来的作业"
• "我注册了哪些课程？"
• "我有新消息吗？"
• "我数学的平均分是多少？"
• "给我看看老师关于这个项目的消息"

基础用法

获取课程：

get_courses()

获取近期成绩：

get_results(limit=10, course_filter="Math", include_details=True)

获取即将到来的作业：

get_future_tasks()

搜索消息：

get_messages(
    limit=20,
    search_query="homework",
    sender_filter="teacher",
    include_body=True
)

📚 详细文档

Claude桌面配置

将此配置添加到你的claude_desktop_config.json文件中：

选项1：使用uvx（推荐）

{
  "mcpServers": {
    "smartschool": {
      "command": "uvx",
      "args": [
        "smartschool-mcp"
      ],
      "env": {
        "SMARTSCHOOL_USERNAME": "your_username",
        "SMARTSCHOOL_PASSWORD": "your_password",
        "SMARTSCHOOL_MAIN_URL": "your-school.smartschool.be",
        "SMARTSCHOOL_MFA": "YYYY-MM-DD"
      }
    }
  }
}

选项2：使用Python模块

{
  "mcpServers": {
    "smartschool": {
      "command": "python",
      "args": [
        "-m",
        "smartschool_mcp"
      ],
      "env": {
        "SMARTSCHOOL_USERNAME": "your_username",
        "SMARTSCHOOL_PASSWORD": "your_password",
        "SMARTSCHOOL_MAIN_URL": "your-school.smartschool.be",
        "SMARTSCHOOL_MFA": "YYYY-MM-DD"
      }
    }
  }
}

选项3：从源代码（用于开发）

{
  "mcpServers": {
    "smartschool": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YourUsername\\path\\to\\Smartschool-MCP",
        "main.py"
      ],
      "env": {
        "SMARTSCHOOL_USERNAME": "your_username",
        "SMARTSCHOOL_PASSWORD": "your_password",
        "SMARTSCHOOL_MAIN_URL": "your-school.smartschool.be",
        "SMARTSCHOOL_MFA": "YYYY-MM-DD"
      }
    }
  }
}

注意： 将C:\Users\YourUsername\path\to\Smartschool-MCP替换为你克隆仓库的实际绝对路径。

配置文件位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

🔧 技术细节

项目结构

Smartschool-MCP/
├── main.py              # 主MCP服务器实现
├── pyproject.toml       # 项目依赖和元数据
├── README.md            # 此文件
└── uv.lock              # 锁定的依赖项

依赖项

• mcp[cli]>=1.9.4 - 模型上下文协议SDK
• smartschool - 智能校园API包装器（自定义分支）

贡献代码

欢迎贡献代码！请随时提交拉取请求。

1. 分叉仓库
2. 创建你的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开拉取请求

📄 许可证

本项目是开源的，可在MIT许可证下使用。

致谢

• 使用 模型上下文协议 构建
• 使用智能校园Python库 (https://github.com/svaningelgem/smartschool)
• 由 Mauro Druwel 创建

免责声明

这是一个非官方工具，与智能校园或其母公司没有关联、未得到其认可或连接。请自行承担使用风险。始终确保你遵守学校的服务条款和可接受使用政策。

支持

如有问题、疑问或建议，请在GitHub上 打开一个问题。

⚠️ 重要提示

你的智能校园凭证存储在环境变量或配置文件中。切勿将凭证提交到版本控制。在生产环境中使用环境变量或安全的秘密管理。如果支持的话，考虑使用特定于应用程序的密码。服务器仅对你的智能校园数据具有只读访问权限。所有通信都在你的AI助手和智能校园API之间本地进行。

故障排除

认证问题

• 验证你的凭证是否正确
• 确保你的MFA日期（出生日期）格式正确：YYYY-MM-DD
• 检查你学校的URL是否正确（不含https://）

连接问题

• 验证你的互联网连接
• 检查是否可以从浏览器访问智能校园
• 确保没有防火墙阻止连接

安装问题

• 确保安装了Python 3.13+
• 验证uv是否正确安装并在你的PATH中
• 尝试运行uv sync重新安装依赖项