School MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@School MCP What do I need on the final to get an A in math?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.comYou 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-mcp2. Install dependencies
npm install3. 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_passwordSecurity note:
.envis listed in.gitignoreand will never be committed. Your password is only used locally to authenticate with your school's server over HTTPS.
4. Build
npm run buildThis 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.jsonTools 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 queryyear— 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 totrueto 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 analyzetargetGrade— desired percentage, e.g.90for 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)) − earnedReturns: 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 simulatehypotheticalScores— 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 |
|
StudentVue API client |
|
Input validation | Zod |
Environment variables | dotenv |
Build tool |
|
Security
Your credentials never leave your machine except for the direct HTTPS connection to your school's StudentVue server. Specifically:
Stored only in
.envon your local diskListed in
.gitignore— cannot be accidentally committedNever 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:
Confirm you ran
npm run buildand thatdist/index.jsexists.Verify the path in
claude_desktop_config.jsonis an absolute path pointing todist/index.js.Fully quit and relaunch Claude Desktop (not just close the window).
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 --watchEvery 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 toolsask_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Your lab results and health record in Claude: trends, retests, meds, conditions and symptoms.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Ask Claude about your income and spending, and import bank statements. No bank login.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects Claude to Canvas LMS, enabling students to query their coursework, assignments, grades, deadlines, announcements, and calendar events through natural conversation instead of navigating the Canvas interface.8-
- FlicenseNot gradedqualityDmaintenanceConnects Claude AI to your Canvas LMS account, enabling natural language interaction with coursework including assignments, grades, announcements, and calendar.-
- AlicenseBqualityCmaintenanceEnables Claude to interact with Canvas LMS, allowing natural language queries about courses, deadlines, grades, and feedback.29MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage student profiles, track assessments, calculate topic mastery, identify learning gaps, and recommend focus areas. Integrates with Claude Desktop and Claude Code for interactive learning analytics.1MIT