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重新安裝依賴項