Skip to main content
Glama

School MCP — StudentVue for Claude

A personal MCP (Model Context Protocol) server that connects Claude to your StudentVue school dashboard. Ask Claude natural-language questions about your grades, GPA, attendance, schedule, and assignments — and get real answers pulled live from your school's gradebook.


What It Does

Once installed, Claude can answer questions like:

  • "What's my GPA right now?"

  • "Am I failing anything?"

  • "What assignments do I have due this week?"

  • "What do I need to get on my next English essay to reach a 90%?"

  • "Which missing assignments are hurting me the most?"

  • "If I got 85, 90, and 95 on my next 3 math tests, what would my grade be?"

  • "Which category (tests vs homework vs quizzes) is killing my science grade?"

  • "What should I focus on this week to improve my GPA the most?"

  • "What's my attendance record?"

  • "Do I have any unread messages from teachers?"

  • "What room is my 3rd period class in?"

Claude has access to 19 tools that fetch live data from your school's StudentVue server on demand.


Related MCP server: Canvas LMS MCP Server

How It Works

This is a local MCP server — a small Node.js process that runs on your machine and communicates with Claude Desktop via stdin/stdout. It never runs in the cloud. Your credentials and school data never leave your computer except for the direct HTTPS request to your school's StudentVue server.

Claude Desktop  ←→  MCP Server (Node.js, local)  ←→  StudentVue (your school's HTTPS server)

The server uses the studentvue npm package (by jwmarb), which wraps the Synergy SOAP API that StudentVue schools expose. A singleton client is created on first tool call and reused for the session to avoid re-authenticating on every request.


Compatibility

Works with any school district that uses Synergy StudentVue (Edupoint). This includes thousands of districts across the US. Your district URL will look like:

https://your-district.edupoint.com

You can find your district URL from the StudentVue web or mobile app login screen.


Prerequisites

  • Node.js 18+

  • Claude Desktop (Mac or Windows app)


Setup

1. Clone or download

git clone https://github.com/YOUR_USERNAME/school-mcp.git
cd school-mcp

2. Install dependencies

npm install

3. Fill in your credentials

Edit .env in the project root:

DISTRICT_URL=https://your-district.edupoint.com
STUDENTVUE_USERNAME=your_student_username
STUDENTVUE_PASSWORD=your_student_password

Security note: .env is listed in .gitignore and will never be committed. Your password is only used locally to authenticate with your school's server over HTTPS.

4. Build

npm run build

This compiles TypeScript to dist/index.js.

5. Add to Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config, and add:

{
  "mcpServers": {
    "school": {
      "command": "node",
      "args": ["/absolute/path/to/school-mcp/dist/index.js"]
    }
  }
}

Replace the path with the actual absolute path to dist/index.js on your system. On Windows use forward slashes:

"args": ["C:/Users/YourName/school-mcp/dist/index.js"]

6. Restart Claude Desktop

After restarting, you'll see a hammer icon (🔨) in Claude's chat input bar indicating tools are available. Ask any question about your grades and Claude will automatically call the right tools.


Project Structure

school-mcp/
├── src/
│   ├── index.ts               # MCP server entry point — creates server, registers all tools
│   ├── client.ts              # StudentVue singleton client (lazy-initialized)
│   └── tools/
│       ├── utils.ts           # Shared helpers: ok(), err(), extractCourses(), parsePoints(), etc.
│       ├── attendance.ts      # get_attendance
│       ├── calendar.ts        # get_calendar
│       ├── documents.ts       # get_documents
│       ├── gradebook.ts       # get_gradebook
│       ├── gpa.ts             # get_gpa
│       ├── messages.ts        # get_messages
│       ├── reportCards.ts     # get_report_cards
│       ├── schedule.ts        # get_schedule
│       ├── schoolInfo.ts      # get_school_info
│       ├── studentInfo.ts     # get_student_info
│       ├── assignmentsDue.ts  # get_assignments_due
│       ├── gradeSummary.ts    # get_grade_summary
│       ├── gradeDetails.ts    # get_grade_details
│       ├── gradeNeeded.ts     # calculate_grade_needed
│       ├── gradeSimulator.ts  # simulate_grade_scenario
│       ├── lowGrades.ts       # get_failing_or_low_grades
│       ├── missingAssignments.ts  # get_missing_assignments
│       ├── categoryBreakdown.ts   # get_category_breakdown
│       └── askAboutGrades.ts      # ask_about_grades
├── dist/                      # Compiled JavaScript (generated by npm run build)
├── .env                       # Your credentials (never committed)
├── .gitignore
├── package.json
└── tsconfig.json

Tools Reference

Core StudentVue Data Tools

These tools call the StudentVue API directly and return raw structured data.

get_attendance

Returns the complete attendance record: absences, tardies, and reason codes broken down by period and date. Useful for checking your total absence count or verifying specific days.


get_calendar

Returns school calendar events for a given month — holidays, early release days, in-service days, and other school events.

Parameters:

  • month (1–12) — month to query

  • year — 4-digit year, e.g. 2025


get_documents

Returns the list of documents available to the student (forms, permission slips, letters from the school). Returns names and metadata only — no binary file content.


get_gradebook

Returns the complete raw gradebook for a reporting period, including all courses, all marks, and every assignment with its score and point value.

Parameters:

  • reportingPeriod (default: 0) — 0 = current grading period, 1 = previous, and so on


get_messages

Returns messages from teachers and school administration with sender name, subject, date sent, and whether the message has been read.

Parameters:

  • unreadOnly (default: false) — set to true to filter to unread messages only


get_report_cards

Returns the list of available report cards with their dates and descriptions. Does not return the full document.


get_schedule

Returns the student's class schedule for the current term: each period with course name, teacher name, room number, and teacher email address.


get_school_info

Returns the school's name, mailing address, phone number, and principal's name.


get_student_info

Returns the student's profile: full name, grade level, student ID, birthdate, and school. The photo binary is stripped from the response to keep it compact and readable.


Analytical Tools

These tools process gradebook data internally to answer specific quantitative questions. You do not need to call get_gradebook before using them.


get_gpa

Computes the student's current unweighted GPA on a 4.0 scale from live gradebook data.

Letter grade → GPA points mapping:

Grade

Points

A / A+

4.0

A-

3.7

B+

3.3

B

3.0

B-

2.7

C+

2.3

C

2.0

C-

1.7

D+

1.3

D

1.0

D-

0.7

F

0.0

Returns: Overall GPA, count of scored courses, and a per-course breakdown with percentage, letter grade, and GPA points for each class.


get_assignments_due

Finds all upcoming assignments due within the next N days across all courses, sorted chronologically.

Parameters:

  • days (default: 7, max: 60) — how many calendar days ahead to look

Returns: Sorted list of assignments with course name, assignment name, due date, point value, assignment type, and current score (if already graded).


get_grade_summary

Returns all courses sorted from lowest grade to highest — the fastest way to see which classes need the most attention.

Returns per course: Course name, period, teacher, current percentage, letter grade. Unscored courses appear at the end.


get_grade_details

Returns deep assignment-level data for a single course: every assignment with name, score, points possible, due date, assignment type, and any teacher notes.

Parameters:

  • courseName — partial or full course name (case-insensitive contains match), e.g. "English", "AP Calc", "Physics"

If the course isn't found, returns a list of available course names to help you get the right name.

Returns: Current grade, total assignment count, how many are scored vs unscored, and the full assignment list.


calculate_grade_needed

Answers: "What score do I need on my next assignment to hit a target grade?"

Parameters:

  • courseName — course to analyze

  • targetGrade — desired percentage, e.g. 90 for a 90%

  • assignmentPoints — total points the upcoming assignment is worth, e.g. 100

Math: Sums all currently scored points (earned) and total possible points (total). Solves for the required score x:

(earned + x) / (total + assignmentPoints) = targetGrade / 100
x = (targetGrade/100 × (total + assignmentPoints)) − earned

Returns: Required points, required percentage, current grade, and whether it's mathematically feasible (i.e., required % ≤ 100%).


simulate_grade_scenario

Answers: "What would my grade be if I scored X, Y, Z on my next assignments?"

Parameters:

  • courseName — course to simulate

  • hypotheticalScores — array of {score, outOf} objects

Example:

hypotheticalScores: [
  { score: 85, outOf: 100 },
  { score: 45, outOf: 50 },
  { score: 18, outOf: 20 }
]

Returns: Current grade, projected grade after hypothetical assignments, letter grade change (e.g. B → A-), and a plain-English interpretation like "After these 3 assignments, your grade in AP Calc would be 91.2% (A-)."


get_failing_or_low_grades

Returns all courses where the student's current grade is below a threshold.

Parameters:

  • threshold (default: 70) — any course below this percentage is returned

Returns: List sorted lowest first, showing current percentage, letter grade, and how many points below the threshold each course is. Includes a message if no courses are below the threshold.


get_missing_assignments

Finds all missing or unscored assignments across every course, sorted by point value so the highest-impact work appears first.

What counts as missing: Score field is empty, equals "Not Graded", or contains the word "Missing".

Returns: Assignment name, course, due date, points possible, and assignment type — ordered so the most grade-damaging missing work is addressed first.


get_category_breakdown

Shows how a student is performing within each assignment category (Tests, Homework, Quizzes, Projects, etc.) for a specific course. Useful for understanding why a grade is what it is.

Parameters:

  • courseName — partial or full course name

How it works: First attempts to use StudentVue's official GradeCalculationSummary which includes category weights (e.g. "Tests = 60%"). If that data is unavailable, falls back to grouping assignments by type and computing raw point totals per category.

Returns: Per-category percentage, points earned/possible, category weight (if available), sorted lowest first.


ask_about_grades

A comprehensive grade data dump for open-ended or complex questions. Returns full data for every course in a single call. Use this when the question doesn't map cleanly to one of the other tools, e.g. "What should I focus on this week?" or "Give me a complete picture of where I stand."

Returns:

  • GPA overview (overall GPA, total courses, scored courses)

  • Top 3 priority courses (lowest grades) with missing assignment counts

  • Per-course data: grade, percentage, letter grade, GPA points, total and missing assignment counts, the last 5 scored assignments, and the full list of missing assignments


Tech Stack

Component

Technology

Runtime

Node.js

Language

TypeScript (strict mode)

MCP Framework

@modelcontextprotocol/sdk

StudentVue API client

studentvue by jwmarb

Input validation

Zod

Environment variables

dotenv

Build tool

tsc (TypeScript compiler)


Security

Your credentials never leave your machine except for the direct HTTPS connection to your school's StudentVue server. Specifically:

  • Stored only in .env on your local disk

  • Listed in .gitignore — cannot be accidentally committed

  • Never sent to Anthropic, Claude's servers, or any third party

  • Only used to authenticate with your school's server (the same one you'd visit in a browser)

Never commit .env to a public repository. Even if you fork or share this project, .env is already in .gitignore.


Troubleshooting

"Missing credentials" error on startup: Make sure .env is in the school-mcp/ directory (same level as package.json) and all three variables are set with real values.

"Login failed" / authentication error: Verify your DISTRICT_URL, username, and password. The URL must start with https:// and exactly match what's shown on the StudentVue web login page. Try signing in at the web version of StudentVue to confirm the credentials are correct.

Tools not showing up in Claude Desktop:

  1. Confirm you ran npm run build and that dist/index.js exists.

  2. Verify the path in claude_desktop_config.json is an absolute path pointing to dist/index.js.

  3. Fully quit and relaunch Claude Desktop (not just close the window).

  4. Check Claude Desktop's Developer settings for MCP server error logs.

"Course not found" error: Use a shorter partial name. For a course called "AP English Language and Composition," try "English" or "AP English". The match is case-insensitive and checks whether your input appears anywhere in the course title.

Grade computation differs from StudentVue: Some districts use weighted category grades that StudentVue calculates server-side. The get_category_breakdown tool will use the official GradeCalculationSummary if available. If not, it falls back to raw point totals which may differ from the weighted grade displayed in StudentVue's UI.


Development

To add a new tool or modify existing ones:

# Recompile after any change
npm run build
# or watch for changes automatically
npx tsc --watch

Every tool follows the same pattern:

// src/tools/myTool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { getClient } from '../client.js';
import { ok, err } from './utils.js';

export function registerMyTool(server: McpServer): void {
  server.tool(
    'tool_name',
    'Description of what this tool does for Claude to read.',
    {
      param: z.string().describe('What this parameter is for'),
    },
    async ({ param }) => {
      try {
        const client = await getClient();
        const data = await client.someMethod();
        return ok(data);
      } catch (e) {
        return err(e instanceof Error ? e.message : String(e));
      }
    }
  );
}

Then import and register it in src/index.ts:

import { registerMyTool } from './tools/myTool.js';
// ...inside main():
registerMyTool(server);

Run npm run build and restart Claude Desktop to pick up the change.

Available Tools

19 tools
ask_about_gradesA

Get a comprehensive grade context dump for any open-ended grade question. Returns full course-by-course data including current grades, all assignments, scores, and missing work. Use this as a starting point for complex analysis like "what should I focus on this week" or "how can I improve my overall GPA."

Inputs: no named parameters.

calculate_grade_neededA

Calculate what score a student needs on an upcoming assignment to reach a target grade in a course. Accounts for the assignment's weight and the existing grade. Returns the required score as a percentage.

Inputs: courseName (required), targetGrade (required), assignmentPoints (required).

get_assignments_dueA

Get upcoming assignments due within the next N days across all courses. Returns assignment name, course, due date, and point value. Useful for planning what to work on.

Inputs: days.

get_attendanceA

Get the student's attendance record including absences, tardies, and reason codes for each period.

Inputs: no named parameters.

get_calendarB

Get school calendar events for a given month. Returns holidays, early releases, and school events.

Inputs: month (required), year (required).

get_category_breakdownB

Get the grade breakdown by assignment category (e.g. Tests, Homework, Quizzes) for a specific course. Shows weight, points earned vs possible, and percentage for each category. Useful for finding which category is dragging down a grade.

Inputs: courseName (required).

get_documentsA

Get the list of documents available to the student (e.g. forms, letters). Returns document names and metadata, not binary content.

Inputs: no named parameters.

get_failing_or_low_gradesA

Get courses where the student is below a given grade threshold. Useful for quickly finding classes at risk of failing or needing improvement.

Inputs: threshold.

get_gpaA

Compute the student's current GPA from live gradebook data. Returns unweighted GPA on a 4.0 scale, plus a per-course breakdown showing course name, percentage, letter grade, and GPA points.

Inputs: no named parameters.

get_gradebookA

Get the full gradebook for a reporting period. Returns all courses with their assignments and scores. Use reportingPeriod 0 for the current period. Increment for previous periods.

Inputs: reportingPeriod.

get_grade_detailsA

Get detailed assignment-level data for a specific course. Returns every assignment with its score, points possible, due date, and type. Use this to deeply analyze a single class.

Inputs: courseName (required).

get_grade_summaryA

Get all courses sorted by current grade from lowest to highest. Quick overview to see which classes need the most attention.

Inputs: no named parameters.

get_messagesB

Get messages from teachers and school administration. Returns message list with sender, subject, date, and read status.

Inputs: unreadOnly.

get_missing_assignmentsA

Find all missing or unscored assignments across every course. Returns them sorted by impact (point value) so the student knows which missing work hurts their grade the most.

Inputs: no named parameters.

get_report_cardsA

Get the list of available report cards for the student. Returns document listing with dates and descriptions.

Inputs: no named parameters.

get_scheduleA

Get the student's class schedule for the current term. Returns each period with course name, teacher, room number, and meeting times.

Inputs: no named parameters.

get_school_infoA

Get information about the student's school including name, address, phone number, and principal.

Inputs: no named parameters.

get_student_infoA

Get the student's profile information including name, grade level, student ID, birthdate, and school. Does not return the photo binary.

Inputs: no named parameters.

simulate_grade_scenarioA

Project what the student's grade would be in a course if they scored hypothetical scores on future assignments. E.g., "what if I got 85, 90, and 95 on my next 3 assignments?"

Inputs: courseName (required), hypotheticalScores (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 19 tools

    Disambiguation4/5

    While there are numerous grade-related tools, each serves a distinct purpose ranging from comprehensive dumps (ask_about_grades) to specific course deep-dives (get_grade_details), projections (simulate_grade_scenario), and filtered views (get_failing_or_low_grades). An agent can distinguish between them based on query specificity.

    Naming Consistency4/5

    Tools overwhelmingly follow a snake_case verb_noun pattern. The three exceptions (ask_about_grades, calculate_grade_needed, simulate_grade_scenario) use action verbs appropriate to their computational or conversational nature rather than simple retrieval, maintaining overall readability.

    Tool Count4/5

    Nineteen tools is slightly above the ideal range but justified by the server's comprehensive coverage of academic analytics. The count reflects necessary granularity for grade analysis without excessive redundancy, though it approaches the upper limit of manageable scope.

    Completeness3/5

    The server covers grade analysis extensively but has notable gaps: while it can list documents, messages, and report cards, it cannot retrieve their actual content. Additionally, there are no tools for submitting assignments or replying to communications, creating dead ends in workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers