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.

---

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.