Smartschool MCP

🚀 Smartschool MCP Server

このModel Context Protocol (MCP)サーバーは、AIアシスタントがSmartschoolプラットフォームと対話し、コース、成績、課題、メッセージにアクセスできるようにします。

🚀 クイックスタート

このMCPサーバーを使用すると、ClaudeなどのAIアシスタントが、ベルギーとオランダで広く使用されている教育管理プラットフォームであるSmartschoolから情報をシームレスにアクセスして取得できます。このMCPサーバーを使えば、学生は会話を中断することなく、AIアシスタントに自分の成績、今後の課題、コース情報、メッセージについて尋ねることができます。

✨ 主な機能

Smartschool 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
• 有効な資格情報を持つSmartschoolアカウント

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 Desktopの構成に追加します
• 環境変数を自動的に設定します

PyPIからの手動インストール

手動でインストールし、後で構成する場合は、次のコマンドを使用します。

# pipを使用する場合
pip install smartschool-mcp

# uvを使用する場合（推奨）
uv pip install smartschool-mcp

手動インストール後、Claude Desktopを手動で構成する必要があります（以下の構成セクションを参照）。

ソースからのインストール

貢献したい場合、または最新の開発バージョンを使用する場合は、次のコマンドを使用します。

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

構成パラメータ

💻 使用例

Claude Desktopまたは他の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 Desktopの構成

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資格情報は環境変数または構成ファイルに保存されます
• 資格情報をバージョン管理にコミットしないでください
• 本番環境では環境変数または安全なシークレット管理を使用してください
• サポートされている場合は、アプリケーション固有のパスワードを使用することを検討してください
• サーバーはあなたのSmartschoolデータに読み取り専用アクセスのみを持ちます
• すべての通信はあなたのAIアシスタントとSmartschool APIの間でローカルで行われます

トラブルシューティング

認証問題

• あなたの資格情報が正しいことを確認してください
• あなたのMFA日付（生年月日）が正しい形式 YYYY-MM-DD であることを確認してください
• あなたの学校のURLが正しいことを確認してください（https:// を除く）

接続問題

• あなたのインターネット接続を確認してください
• Smartschoolがあなたのブラウザからアクセス可能であることを確認してください
• ファイアウォールが接続をブロックしていないことを確認してください

インストール問題

• Python 3.13以上がインストールされていることを確認してください
• uvが正しくインストールされ、PATHに含まれていることを確認してください
• 依存関係を再インストールするために uv sync を実行してみてください

開発

プロジェクト構造

Smartschool-MCP/
├── main.py              # メインのMCPサーバー実装
├── pyproject.toml       # プロジェクトの依存関係とメタデータ
├── README.md            # このファイル
└── uv.lock              # ロックされた依存関係

依存関係

• mcp[cli]>=1.9.4 - Model Context Protocol SDK
• smartschool - Smartschool APIラッパー（カスタムフォーク）

貢献

貢献は大歓迎です！プルリクエストを送信してください。

1. リポジトリをフォークします
2. あなたの機能ブランチを作成します (git checkout -b feature/AmazingFeature)
3. あなたの変更をコミットします (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュします (git push origin feature/AmazingFeature)
5. プルリクエストを開きます

📄 ライセンス

このプロジェクトはオープンソースで、MITライセンスの下で利用可能です。

クレジット

• Model Context Protocol を使用して構築されています
• Smartschool Pythonライブラリ (https://github.com/svaningelgem/smartschool) を使用しています
• Mauro Druwel によって作成されました

免責事項

これは非公式のツールであり、Smartschoolまたはその親会社とは関係がなく、承認もされておらず、関連もありません。自己責任で使用してください。常に学校の利用規約と許容使用ポリシーに準拠していることを確認してください。

サポート

問題、質問、または提案がある場合は、GitHubでissueを開いて ください。