smartschool-mcp

Smartschool MCP Server

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

    

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.