GPA Calculator MCP
[npm]
[downloads]
[license]
[Star on GitHub]
GPA Calculator MCP is a free, open source MCP server, published on npm as gpa-calculator-mcp. It is a GPA calculator for AI apps. Ask it to work out your GPA, your cumulative GPA (CGPA), your semester GPA (SGPA) or your weighted GPA with credit multipliers, plan the GPA you need to hit a target and the grade each upcoming course needs, convert grades between letters and percentages, do a GPA scale conversion for a UK class or an Australian grade, and figure out the grade needed on the final. The math is done by tested code, not guessed by the model.
Use it with Claude, ChatGPT, Cursor, VS Code Copilot and any other app that supports MCP. It runs on your computer, needs no internet and no login, and never sees your school account.
Free forever. No account and no subscription.
Install
Run it straight from npm with npx. You need Node.js 20 or newer, see Node version for the details. There is nothing else to install, no account and no config file for the server itself.
Add it to your AI app's MCP config so the app can start it for you. Every app reads its config from its own file, so pick yours:
All of them start the same server the same way. The only difference is where the config goes.
Claude Desktop
Add this to claude_desktop_config.json:
Restart Claude Desktop after you save the file.
Claude Code
Run this in a terminal:
ChatGPT
The ChatGPT desktop app can start a server that runs on your computer. Open Settings, choose MCP servers, add a server, pick STDIO and give it the command npx with the arguments -y gpa-calculator-mcp. Save the server and restart the app.
The desktop app, the Codex CLI and the IDE extension read the same config file, ~/.codex/config.toml, so you can write the server there instead:
Type /mcp in a chat to see the servers that are connected.
The ChatGPT website talks to servers over the web, so it needs a public HTTPS address. Put a tunnel in front of a server that runs on your computer, then add it as a custom MCP server from the Plugins page.
Cursor
Cursor reads mcp.json from the project folder at .cursor/mcp.json, or from your home folder at ~/.cursor/mcp.json if you want the server in every project. On Windows the home folder file is %USERPROFILE%\.cursor\mcp.json.
Restart Cursor after you save the file. The Customize page in the sidebar lists the server once it starts, and you can turn it on or off there.
VS Code Copilot
Put this in .vscode/mcp.json in your project folder, or in the mcp.json file in your user profile:
VS Code also reads a portable .mcp.json file in the project root. That file uses the name mcpServers instead of servers:
Restart VS Code after you save the file.
After any of these, try one of the prompts below.
Try these three prompts
-
What do I need on the final?
"My grade is 85% and the final is worth 40% of the course. What do I need on the final to finish with a B+?"
The model calls needed_on_final with current_percent 85, final_weight_percent 40 and target_letter "B+" on the us4 scale. B+ starts at 87% on that scale, so you need 90% on the final to reach it.
Ask for a percentage target instead and the tool does the same sum. With current_percent 74, final_weight_percent 40 and target_percent 80, the other 60% of the course is locked in, so you need 89% on the final to reach 80%.
-
What is my GPA?
"What's my GPA if I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits?"
calculate_gpa returns 3.12 across 10 credits on the us4 scale, with a per course breakdown.
-
Convert a grade
"Convert 78 percent to a letter grade on the Ontario college scale."
convert_grade returns the letter, the percentage range it covers and the grade points, using the ontario-college scale.
More things you can ask:
- "I have a 3.1 GPA over 60 credits. What GPA do I need next semester to reach 3.4?"
- "I have a 3.4 GPA over 60 credits. What do I need in each of my four classes next semester to reach 3.5?"
- "My course is 20% quizzes, 30% labs, 50% exam. I have 85 on quizzes and 70 on labs. What's my grade so far and what's the best I can finish with?"
- "What's my GPA on the UK classification scale if I got a 2:1, a 2:2 and a first?"
- "What's my CGPA? I had a 3.2 GPA over 45 credits and this term I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits."
- "What's my weighted GPA if my two AP classes count 1.1 times the credits?"
- "I have a 3.5 GPA on the US 4.0 scale. What is that in the UK?"
- "Show me the grade scales you have built in."
Tools
Eight tools. These names are the ones your AI app sees.
Every tool description sent to your AI app ends with one example prompt, so the model can match a question like "What do I need on the final?" to the right tool and fill in every parameter.
Every tool also returns the same numbers as structured data. Each tool has an output schema, so a client that reads JSON gets fields such as term_gpa or needed_percent straight away, and the text answer stays the same for an app that only reads words. The fields each tool returns are listed in llms.txt and in glama.json.
Grade scales
The scale parameters take one of these six ids. A client that reads the tool schema sees them as the allowed values, and any other value is rejected before the tool runs.
Schools differ. Run list_scales to see the exact table used, and tell your AI if your school's cutoffs are different.
The two UK and Australian scales turn a class or a letter into grade points so the GPA tools can add up your work. For the UK table, a first is 4.0, a 2:1 is 3.3, a 2:2 is 2.7 and a third is 2.0. A UK degree is normally reported as a class, not a GPA, so treat those points as a way to compare and plan, not as an official number. Pass a class in a letter field as 1st, 2:1, 2:2 or 3rd, or pass a percentage and the server picks the class for you. The weighted-5.0 table is a plain mapping rather than one school's official table: it keeps the us4 cutoffs and puts every letter above F one point higher, so an A is 5.0. Pick it when your school reports a weighted GPA on a 5.0 top.
Run convert_gpa_scale to read a GPA on one scale as the nearest band on another, so a US 4.0 GPA can be read as a UK class or an Australian grade. It reads the GPA as a share of the top grade point on its own scale and picks the nearest band on the target scale. That is a comparison, not an official conversion, so check the target school's table.
Import a transcript
Pass transcript_csv to calculate_gpa with your whole transcript as a CSV string. A header row is optional, the columns can be in any order, and headers like Course Title, Final Grade and Credit Hours are read as the name, grade and credits columns. A plain no header CSV works too, with columns in the order name, credits, grade.
Example:
Rows with P, NP or W grades are left out of the GPA and named in the answer, except a P on the australia-hd scale, where P counts. If a header row has no credits or grade column, the tool says which column is missing. When courses is not given, transcript_csv is parsed and used as the course list.
FAQ
What is the difference between CGPA and SGPA?
SGPA is the GPA for one term, so the GPA for the courses you pass in. CGPA is the cumulative GPA over every term you have finished. calculate_gpa gives you the term GPA for the courses you pass. Add your earlier GPA and credits as prior_gpa and prior_credits and the tool also gives the cumulative GPA.
Can I include my GPA from last semester?
Yes. Pass your earlier GPA as prior_gpa and your earlier credits as prior_credits to calculate_gpa, along with this term's courses. The tool folds them into a cumulative GPA. Pass both together. Passing only one of the two is an error, so the tool says which one is missing instead of quietly leaving the earlier terms out.
Can I give an AP class more weight?
Yes. Pass credit_multiplier on a course in calculate_gpa, for example 1.1 for an AP class that counts 1.1 times the credits. The plain term_gpa stays the same as it was, and the answer adds a weighted_gpa with the multipliers applied plus the weighted credits. Schools differ, so ask which multiplier yours uses. The weighted GPA covers the courses in that call, while the cumulative GPA keeps using the plain credits.
What about pass, fail and withdrawn courses on my transcript?
Pass transcript_csv to calculate_gpa with your whole transcript. A P is read as pass, NP as not pass and W as withdrawn. Those rows are left out of the GPA and named in a "Not counted in the GPA:" line, so the credits and the average only cover graded work. The one exception is a P on the australia-hd scale, where P is a graded pass worth grade points and still counts.
Portal exports with different column names work as they are: headers like Course Title, Final Grade and Credit Hours are read as the course name, grade and credits columns, in any column order. A header row that has no credits or grade column gets an error that names what is missing, instead of a parse failure further in.
What if my school uses a 4.3 scale?
Use the us4plus scale. It is the us4 scale with A+ worth 4.3. Pass scale "us4plus" to calculate_gpa, convert_grade or target_gpa_planner. Run list_scales to see the full table.
What grade do I need to pass?
It depends on your school and program. On the built in us4 scale, D covers 63 to 66 percent and is usually the lowest passing grade, but many programs require a C or higher. Use needed_on_final to work out what you need on the final, or target_gpa_planner to plan a cumulative GPA. Check your school's handbook for the real cutoff.
Can I ask for a letter grade instead of a percentage?
Yes. Pass target_letter to needed_on_final, for example target_letter "B+", and the tool looks the cutoff up in the scale table. Pass scale "uk-classification" for a UK class such as 2:1. You can pass target_percent as well, and the tool works to the higher of the two.
How do I convert my GPA to a UK or Australian scale?
Use convert_gpa_scale. Pass your GPA as gpa and the scale it is on as from_scale. Leave to_scale out and the tool gives the nearest band on both the uk-classification and australia-hd scales, or pass one of them to get only that one. It reads your GPA as a share of the top grade point on its own scale and picks the nearest band on the target scale. That is a comparison, not an official conversion, so check the target school's table.
Do my course parts have to add up to 100?
No. Every weight in weighted_grade is a percentage of the whole course, so you can pass only the parts you know. If you pass 20 percent quizzes and 30 percent labs with scores of 85 and 70, the tool says your grade so far is 76 percent, which banks 38 of the 100 points the course is worth, you finish at 38 percent if you score 0 on everything left, and you finish at 88 percent if you score 100 on everything left. The other 50 percent of the course is still to come. Weights that add up to more than 100 are an error, because a course is graded out of 100.
Can a script read the numbers without reading the sentence?
Yes. Every tool has an output schema and returns the numbers as fields next to the text, so a script can read term_gpa or needed_percent without taking them out of the sentence. The text answer is the same as it has always been.
How it compares
For a student who just wants the number, a focused offline calculator avoids signing in, avoids connecting to a school server and keeps the task to arithmetic. If you already pull grades from an LMS, you can still pass those numbers to this calculator.
Use it with Brightspace or Canvas MCP
If you already pull grades from your learning system, you can combine them with this calculator. Brightspace MCP and Canvas MCP can fetch your grades from your course sites. Then you can ask this server to work out your GPA or figure out what you need on the final.
- Pull your grades with Brightspace MCP, then call
calculate_gpa or needed_on_final on the numbers it gives you.
- Pull your grades with Canvas MCP, then call
calculate_gpa or needed_on_final on the numbers it gives you.
Both are free and open source. See the list below for links.
Troubleshooting
If npx -y gpa-calculator-mcp fails or hangs:
- Check your Node.js version with
node --version. The server needs Node.js 20 or newer, see Node version.
- Delete the folder where npx keeps its downloads, then try again. On Windows it is
%LocalAppData%\npm-cache\_npx, and on macOS and Linux it is ~/.npm/_npx.
- Make sure your computer can reach
registry.npmjs.org. On a school network or behind a proxy, npm may need the proxy settings from your network's owner.
- If
node or npx is not found on Windows, reinstall Node.js with "Add to PATH" checked, then restart your terminal.
Node version
There are two floors here, and they are not the same number.
The server itself is happy on Node.js 20, and that is what engines in package.json says. The test runner wants a newer Node.js, so the development floor lives in devEngines in the same file. npm checks devEngines before install, run and test, so a clone on Node.js 20 stops with a clear message instead of a strange failure part way through the test suite. The 23 and 25 release lines are left out on purpose, because the test runner does not run on them.
Both numbers live in package.json, and a test in tests/node-version.test.ts keeps them in step with the README and with the range the test runner asks for.
Development
The tests call every tool through a real MCP client, so they need no account or network. They need the newer Node.js from the Node version section above, because of the test runner.
More free student MCP servers
All free, open source and read only where they touch your accounts. Browse the full list at brightspacemcp.com/more-mcps.
License
MIT
