skyward-mcp

Unofficial self hosted Skyward MCP for students and educators.

Connect ChatGPT, Claude, or another MCP client to the Skyward account that the person running the server is already authorized to use.

What this is

skyward-mcp is the MCP application layer built on top of skyward-rest.

The split is intentional:

skyward-rest
  typed Skyward client
  authenticated transport
  provider adapters
  safe parsers

skyward-mcp
  MCP tools
  local setup
  ChatGPT OAuth
  browser SSO
  role aware privacy
  future write approvals

The project is designed around user hosted access. It does not require a centrally registered Skyward OAuth application.

Related MCP server: Merlin MCP

Current status

The first release is deliberately read only.

Current tools:

The current skyward-rest SMS 2.0 provider implements the student read surfaces that have actually been rebuilt and tested from modern route discovery.

Teacher, parent, staff, Qmlativ, broader profile data, calendar event parsing, and SIS write support remain extension points rather than fake claims of support.

Authentication model

There are two separate authentication layers.

ChatGPT / Claude
        |
        | MCP authorization
        v
   skyward-mcp
        |
        | authenticated Skyward session
        v
      Skyward

MCP authentication

Hosted mode uses MCP_AUTH_TOKEN.

ChatGPT can connect using the built in OAuth 2.1 compatibility flow with PKCE. The authorization page asks for the same MCP_AUTH_TOKEN configured on the deployment.

Other MCP clients may use that secret directly as a Bearer token.

Skyward authentication

skyward-mcp supports browser SSO capture, local session files, hosted session secrets, and compatible classic SMS 2.0 native login.

The password path is only for Skyward deployments that still allow that login flow.

If the district requires SSO, skyward-mcp does not ask for Microsoft, Google, ClassLink, Clever, or other identity provider passwords.

Browser SSO is implemented locally with the intended architecture:

real district browser login
        |
        | user completes SSO and MFA normally
        v
authenticated Skyward browser session
        |
        | imported into the self hosted instance
        v
SkywardSession
        |
        v
skyward-rest

Run npm run setup:sso. A temporary local Chrome, Edge, or Chromium profile opens to the real district login. Complete SSO and MFA normally. skyward-mcp ignores off origin identity provider traffic and waits until Skyward itself emits the resulting SMS session fields, then saves only the Skyward session locally.

Local setup

Requirements:

• Node.js 20 or newer

• npm

git clone https://github.com/caleb-mau/skyward-mcp.git
cd skyward-mcp
npm install
npm run setup

The setup command opens a page on 127.0.0.1.

For a compatible classic SMS 2.0 login, enter the Skyward login URL, username, and password. The local process authenticates directly with that Skyward instance and saves only the resulting session.

The password is not persisted.

Browser SSO

For districts that use Microsoft, Google, ClassLink, Clever, SAML, or another browser based login:

npm run setup:sso

You can also provide the starting Skyward URL:

npm run setup -- --sso "https://skyward.example.net/"

The command opens an installed Chrome, Edge, or Chromium browser in a temporary profile. Complete the district login and MFA normally.

skyward-mcp only inspects requests whose origin matches the Skyward origin and only extracts the resulting Skyward session fields needed by skyward-rest. It does not store the identity provider password, SAML assertion, Microsoft token, Google token, or other off origin authentication traffic.

Once the complete Skyward session is observed, the browser closes and the session is saved locally.

The default session path is:

~/.skyward-mcp/session.json

The file is written with restrictive permissions.

Import an existing session

If another local browser flow produces a SkywardSessionExport:

npm run setup -- --import-session ./skyward-session.json

The session is validated through skyward-rest before it is saved.

Run locally over stdio

npm run start:stdio

Example MCP configuration:

{
  "mcpServers": {
    "skyward": {
      "command": "npm",
      "args": ["run", "start:stdio", "--silent"],
      "cwd": "/absolute/path/to/skyward-mcp"
    }
  }
}

Deploy to Vercel

Vercel is the easiest hosted path.

First authenticate locally once. For a district using SSO:

git clone https://github.com/caleb-mau/skyward-mcp.git
cd skyward-mcp
npm install
npm run setup:sso

For a compatible native Skyward login, npm run setup is still available.

Then generate the two values Vercel needs:

npm run vercel:env

The command prints:

MCP_AUTH_TOKEN=...
SKYWARD_SESSION_B64=...

Treat both values as secrets. SKYWARD_SESSION_B64 is base64 encoding for safe copy and paste, not encryption.

Now use the one click deployment:

Paste those two values when Vercel asks for environment variables. Next.js is detected automatically and no database is required.

Your MCP endpoint will be:

https://your-deployment.vercel.app/mcp

The hosted server also supports these alternatives:

Using a saved session is preferred over storing the Skyward password in Vercel.

A Skyward session can expire. When it does, authenticate locally again, rerun npm run vercel:env, replace SKYWARD_SESSION_B64 in Vercel, and redeploy.

Interactive SSO runs locally rather than inside Vercel. After npm run setup:sso succeeds, run npm run vercel:env and deploy the resulting session exactly the same way as a native Skyward session. Vercel does not need to know whether the original login used Microsoft, Google, ClassLink, Clever, MFA, or native Skyward authentication.

ChatGPT

Add the hosted /mcp URL and use OAuth.

The built in OAuth flow is separate from Skyward authentication. It only proves that the person connecting ChatGPT owns the self hosted MCP deployment.

The OAuth implementation supports:

• Authorization code flow

• PKCE S256

• ChatGPT CIMD client metadata

• Short lived access tokens

• Refresh tokens

• Deployment scoped resources

Discover Skyward routes

Skyward installations vary by district, generation, role, and portal version. The local discovery recorder helps map the authenticated web traffic without exporting the underlying school records.

Run:

npm run discover

Or provide the initial Skyward URL directly:

npm run discover -- --url "https://skyward.example.net/scripts/wsisa.dll/WService=wsEAplus/seplog01.w"

The recorder:

• Opens installed Google Chrome, Microsoft Edge, or Chromium in a temporary profile

• Lets the user complete the district's real login, SSO, and MFA normally

• Captures only requests whose origin exactly matches the configured Skyward origin

• Ignores Microsoft, Google, ClassLink, Clever, and other off origin authentication traffic

• Records paths, HTTP methods, query field names, form field names, selected safe action constants, status codes, content types, table ID patterns, form structure, same origin links, and referenced Skyward endpoints

• Writes a machine readable routes.json and a human readable routes.md

• Deletes the temporary browser profile when discovery ends

The export intentionally does not write raw response bodies, response text, cookies, authorization headers, passwords, or raw session token values.

By default, files are written under:

~/.skyward-mcp/discovery/<timestamp>/

When you are finished clicking through Skyward, return to the terminal and press Enter.

Useful options:

--url URL
--capture-origin URL
--out PATH
--browser-path PATH

The exact origin restriction is deliberate. If a district starts on one hostname but the actual Skyward portal lives on another, pass the final Skyward portal origin with --capture-origin. Do not set an identity provider as the capture origin.

Even sanitized exports should be reviewed before they are shared or committed. The sanitizer is designed to remove record values while preserving protocol structure, but no automated redaction system should be treated as a guarantee against every district specific field.

Privacy and safety

Skyward is an official student information system. The project treats its data accordingly.

The MCP does not expose:

• Skyward passwords

• Skyward cookies

• SMS session tokens

• Raw session exports

Normal status output contains only a redacted session summary and provider capabilities.

The current release contains no SIS write tools.

Read PRIVACY.md and SECURITY.md before using real education records.

Students and educators

The architecture is not student only.

skyward-rest models roles and capabilities for:

• Students

• Teachers

• Parents

• Staff

skyward-mcp uses capability discovery rather than assuming every authenticated identity has the same Skyward surface.

Teacher tools will be added when their actual Skyward endpoints and data structures are tested. Future teacher responses should minimize student identity data instead of exposing every field available to the underlying account.

Relationship to Skyward

This is an unofficial open source project and is not affiliated with or endorsed by Skyward, Inc.

Users are responsible for complying with their district policies and only accessing records they are authorized to access.

Development

npm install
npm test
npm run typecheck
npm run build

Use fictional or heavily sanitized test data only.

See CONTRIBUTING.md.

License

MIT. See LICENSE.