# 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`](https://www.npmjs.com/package/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

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

### 2. Install dependencies

```bash
npm install
```

### 3. Fill in your credentials

Edit `.env` in the project root:

```env
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

```bash
npm run build
```

This compiles TypeScript to `dist/index.js`.

### 5. Add to Claude Desktop

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

```json
{
  "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:

```json
"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:

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

Every tool follows the same pattern:

```typescript
// 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`:

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

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