Smartschool MCP Server

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

Tools

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.

Comparing modes

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 — OAuth 2.1 login flow

One hosted server instance serves any Smartschool user via OAuth 2.1. Users authenticate through a browser-based login form during the authorization flow.

export MCP_ISSUER_URL="https://your-domain.example.com"  # public server URL

smartschool-mcp --transport streamable-http --universal \
  --issuer-url "$MCP_ISSUER_URL" \
  --host 0.0.0.0 --port 8000

In claude.ai → Settings → Integrations → Add custom integration:

• URL: https://your-domain.example.com/mcp

How it works:

1. Claude.ai discovers OAuth endpoints at https://your-domain.example.com/.well-known/oauth-authorization-server
2. Claude.ai registers a client dynamically via /register
3. Claude.ai directs the user to /authorize?... (OAuth authorization endpoint)
4. User is redirected to a login form at /smartschool-login
5. User enters: School URL, Username, Password, and optional MFA (date of birth)
6. On successful login, the server generates an authorization code
7. Claude.ai exchanges the code for an access token (via /token with PKCE)
8. Claude.ai uses the Bearer token on all subsequent /mcp requests

Security: Credentials are never stored in URLs or environment variables. They're collected via HTTPS form submission and validated against Smartschool. Only access tokens are sent with API requests.

Making the server publicly accessible

Required for universal mode. Claude.ai requires HTTPS and must be able to reach your server to redirect users to the login form and receive authorization callbacks.

Some options:

After setting up the tunnel/proxy, your server will be reachable at https://your-domain.example.com. Use this as MCP_ISSUER_URL.

Environment variables

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.