loading…
Spring AI MCP Server
Provides auto-configuration for setting up an MCP server in Spring Boot applications.
автор: Community
0.00
Search for a command to run...
loading…
Enables natural language queries about grades, GPA, attendance, and schedules by connecting Claude to StudentVue school dashboards. Includes analytical tools fo
Enables natural language queries about grades, GPA, attendance, and schedules by connecting Claude to StudentVue school dashboards. Includes analytical tools for grade simulation, what-if scenarios, and academic performance tracking based on live school data.
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.
Once installed, Claude can answer questions like:
Claude has access to 19 tools that fetch live data from your school's StudentVue server on demand.
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.
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.
git clone https://github.com/YOUR_USERNAME/school-mcp.git
cd school-mcp
npm install
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:
.envis listed in.gitignoreand will never be committed. Your password is only used locally to authenticate with your school's server over HTTPS.
npm run build
This compiles TypeScript to dist/index.js.
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"]
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.
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
These tools call the StudentVue API directly and return raw structured data.
get_attendanceReturns 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_calendarReturns 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. 2025get_documentsReturns 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_gradebookReturns 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 onget_messagesReturns 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 onlyget_report_cardsReturns the list of available report cards with their dates and descriptions. Does not return the full document.
get_scheduleReturns the student's class schedule for the current term: each period with course name, teacher name, room number, and teacher email address.
get_school_infoReturns the school's name, mailing address, phone number, and principal's name.
get_student_infoReturns 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.
These tools process gradebook data internally to answer specific quantitative questions. You do not need to call get_gradebook before using them.
get_gpaComputes 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_dueFinds 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 lookReturns: Sorted list of assignments with course name, assignment name, due date, point value, assignment type, and current score (if already graded).
get_grade_summaryReturns 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_detailsReturns 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_neededAnswers: "What score do I need on my next assignment to hit a target grade?"
Parameters:
courseName — course to analyzetargetGrade — desired percentage, e.g. 90 for a 90%assignmentPoints — total points the upcoming assignment is worth, e.g. 100Math: 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_scenarioAnswers: "What would my grade be if I scored X, Y, Z on my next assignments?"
Parameters:
courseName — course to simulatehypotheticalScores — array of {score, outOf} objectsExample:
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_gradesReturns all courses where the student's current grade is below a threshold.
Parameters:
threshold (default: 70) — any course below this percentage is returnedReturns: 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_assignmentsFinds 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_breakdownShows 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 nameHow 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_gradesA 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:
| 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) |
Your credentials never leave your machine except for the direct HTTPS connection to your school's StudentVue server. Specifically:
.env on your local disk.gitignore — cannot be accidentally committedNever commit .env to a public repository. Even if you fork or share this project, .env is already in .gitignore.
"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:
npm run build and that dist/index.js exists.claude_desktop_config.json is an absolute path pointing to dist/index.js."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.
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.
Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"school-mcp": {
"command": "npx",
"args": []
}
}
}