Smartschool MCP

by MauroDruwel

2 stars
29 downloads
Not rated
GitHub

About

Smartschool MCP: A Model Context Protocol (MCP) server that enables seamless communication between AI agents and the Smartschool platform. 🧠

Details

Author
MauroDruwel
GitHub stars
2
Downloads
29
Categories
Other

Jump to

- List enrolled courses with teacher info
- View grades with filtering, pagination, and statistics
- Retrieve upcoming assignments organised by date
- Browse inbox, sent, and trash messages with search
- Fetch day schedule by offset
- Access academic terms and report cards
- Get planner items for the next N days
- Download message attachments

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Smartschool MCP
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Install it with uvx mcp install smartschool-mcp and set environment variables (SMARTSCHOOL_USERNAME, SMARTSCHOOL_PASSWORD, SMARTSCHOOL_MAIN_URL, and optionally SMARTSCHOOL_MFA). For Claude Desktop, add the configuration to claude_desktop_config.json. For remote use on claude.ai, run the server with --transport streamable-http in single‑user or universal mode, then configure a custom integration in claude.ai with the server URL and credentials.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "smartschool mcp": {
            "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"
                }
            }
        }
    }
}

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"
        }
    }
}

Smartschool MCP Server

<!-- mcp-name: io.github.MauroDruwel/smartschool-mcp -->

CI
codecov
PyPI version
License: MIT
Python 3.10+

Connect Claude (and other MCP clients) to your Smartschool account — ask about grades, assignments, messages, and your schedule in plain language.

Tools

| Tool | What it does |
|------|-------------|
| get_courses | List enrolled courses with teacher info |
| get_results | Grades with optional filtering, pagination, and statistics |
| get_future_tasks | Upcoming assignments organised by date |
| get_messages | Inbox/sent/trash with search, sender filter, and body retrieval |
| get_schedule | Day schedule by offset (0 = today, 1 = tomorrow, …) |
| get_periods | Academic terms for the current school year |
| get_reports | Available report cards |
| get_planned_elements | Planner items for the next N days |
| get_student_support_links | School support resources and links |
| get_attachments | List attachments for a specific message |
| download_attachment | Download a specific attachment by message and file ID |

Quick start — Claude Desktop

uvx mcp install smartschool-mcp \
  -e SMARTSCHOOL_USERNAME="you" \
  -e SMARTSCHOOL_PASSWORD="secret" \
  -e SMARTSCHOOL_MAIN_URL="school.smartschool.be" \
  -e SMARTSCHOOL_MFA="YYYY-MM-DD"

Or add it manually to claude_desktop_config.json:

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

Config file locations: %APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · ~/.config/Claude/claude_desktop_config.json (Linux)

Remote / claude.ai

The server supports Streamable HTTP transport for use as a remote integration on claude.ai.

Single-user mode

One server instance, your credentials in environment variables:

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"   # optional but recommended

smartschool-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Add to claude.ai → Settings → Integrations:
- URL: https://your-domain.example.com/mcp
- Authorization header: Bearer <your MCP_API_KEY> (if set)

Universal mode

One hosted server instance serves any Smartschool user — no per-user deployment needed.

smartschool-mcp --transport streamable-http --universal --host 0.0.0.0 --port 8000

Credentials are passed on every request:

| What | Where | Example |
|------|-------|---------|
| School URL | URL query param school | ?school=myschool.smartschool.be |
| Date of birth (MFA) | URL query param mfa | &mfa=2000-01-15 |
| Username | OAuth Client ID | your Smartschool username |
| Password | OAuth Client Secret | your Smartschool password |

In claude.ai → Settings → Integrations → Add custom connector:
- URL: https://your-domain.example.com/mcp?school=myschool.smartschool.be&mfa=YYYY-MM-DD
- OAuth Client ID: your Smartschool username
- OAuth Client Secret: your Smartschool password

> MFA is your date of birth in YYYY-MM-DD format. Omit the mfa param if your account does not require it.

Making the server publicly accessible

Claude.ai requires HTTPS. Some options:

| Option | Command |
|--------|---------|
| Cloudflare Tunnel | cloudflared tunnel --url http://localhost:8000 |
| ngrok | ngrok http 8000 |
| VPS | nginx / Caddy with a Let's Encrypt cert |

Environment variables

| Variable | CLI flag | Default | Description |
|----------|----------|---------|-------------|
| MCP_TRANSPORT | --transport | stdio | stdio or streamable-http |
| MCP_HOST | --host | 0.0.0.0 | Bind address (HTTP only) |
| MCP_PORT | --port | 8000 | Port (HTTP only) |
| MCP_API_KEY | — | — | Static Bearer token (single-user mode) |
| MCP_UNIVERSAL | --universal | off | Enable universal mode (set to 1, true, or yes) |
| SESSION_TTL_SECONDS | — | 3600 | How long to cache sessions (universal mode) |
| SMARTSCHOOL_USERNAME | — | — | Your Smartschool username |
| SMARTSCHOOL_PASSWORD | — | — | Your Smartschool password |
| SMARTSCHOOL_MAIN_URL | — | — | School hostname, e.g. school.smartschool.be |
| SMARTSCHOOL_MFA | — | — | Date of birth YYYY-MM-DD (if required) |

Contributing

PRs are welcome. Run uv sync --extra dev to install dev dependencies, then uv run pytest / uv run ruff check . / uv run mypy smartschool_mcp/ before submitting.

Disclaimer

Unofficial tool, not affiliated with Smartschool. Use in accordance with your school's terms of service.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "smartschool mcp": {
            "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"
                }
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other