Study Planner MCP Server

Study Planner MCP

Offline exam planning for your AI: no account, no login, no internet needed, nothing stored. Free forever, open source.

Give it your exam dates and how many hours you can study, the same on every day or different for each weekday, and get back a day by day plan with spaced repetition review dates, pomodoro blocks with breaks, and dated milestones for a big assignment. Ask for a revision timetable, an exam schedule or the spaced repetition dates for a topic, and it works them out from your dates and your hours. The date math is done by tested code, not guessed by the model.

Why not just use Brightspace tools

Brightspace and Canvas tools read your school site. They tell you what is due, what your grades are and what your teachers announced, and they need an account and a sign in. This server reads no site at all. You give it the exam dates and the hours you can study, and it works out the timetable, the review dates and the breaks. Run it next to an LMS server if you like: one tells you what is assigned, the other tells you how to study it.

Prompt gallery

Copy and paste any of these into your AI app once the server is installed.

• "Plan 3 weeks of study for my 4 exams"
• "What should I study today?"
• "When should I review what I learned today for my exam on Nov 30?"
• "Plan 3 hours of studying as pomodoro blocks with breaks."
• "Break my 6 hour essay due Friday into milestones."

Ask it things like:

• "I have a networking exam on Dec 12 and scripting on Dec 15. I can study 3 hours a day except Sundays. Make me a plan."
• "I have a networking exam on Dec 12. I study 2 hours on weekdays and 6 hours on weekends. Make me a plan."
• "My networking exam covers routing, switching and security. Split the study hours over those topics and tell me what to study today."
• "When should I review what I learned today so I remember it for my exam on Nov 30?"
• "What should I study today? My networking exam is on Dec 12 and I studied routing last Friday."
• "Am I on track for my exam on Dec 12 if I can study 2 hours a day?"
• "Plan 3 hours of studying as pomodoro blocks with breaks."
• "Break my 6 hour essay due Friday into milestones."
• "Give me this plan as an .ics file so I can import it into Google Calendar."

This is a free, open source MCP server. It works with Claude, ChatGPT, Cursor, VS Code Copilot and any other app that supports MCP. It runs on your computer, so your study data never leaves it. The install steps below have the exact config for each app.

Install

The server runs on your computer through npx, so you need Node.js 20 or newer. There is no account, no key and nothing to sign in to.

Every app reads its MCP config from its own file, so pick yours:

• Claude Desktop
• Claude Code
• ChatGPT
• Cursor
• VS Code Copilot

All of them start the same server the same way. The only difference is where the JSON goes.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "study-planner": {
      "command": "npx",
      "args": ["-y", "study-planner-mcp"]
    }
  }
}

Restart Claude Desktop after you save the file.

Claude Code

Run this in a terminal:

claude mcp add study-planner -- npx -y study-planner-mcp

ChatGPT

The ChatGPT desktop app can start a server that runs on your machine. Open Settings, turn on developer mode, add a connector and paste this JSON:

{
  "mcpServers": {
    "study-planner": {
      "command": "npx",
      "args": ["-y", "study-planner-mcp"]
    }
  }
}

The ChatGPT website talks to servers over the web, so use the desktop app for a server that runs on your computer.

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.

{
  "mcpServers": {
    "study-planner": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "study-planner-mcp"]
    }
  }
}

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:

{
  "servers": {
    "study-planner": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "study-planner-mcp"]
    }
  }
}

VS Code also reads a portable .mcp.json file in the project root. That file uses the name mcpServers instead of servers:

{
  "mcpServers": {
    "study-planner": {
      "command": "npx",
      "args": ["-y", "study-planner-mcp"]
    }
  }
}

Restart VS Code after you save the file.

After any of these, try one of the questions at the top of this page.

Tools

The original names make_study_plan, spaced_repetition_dates, pomodoro_plan and assignment_milestones do the same four jobs with the same parameters, so existing configs and saved prompts keep working.

Every date these tools take can be written in plain words, like Dec 12 or in 3 weeks. See Dates in plain words.

Study Planner MCP compared with Brightspace and Canvas

Brightspace MCP and Canvas MCP read your school site. They tell you what is due, what your grades are and what your teachers announced. They need an account and a sign in.

This server reads no site at all. You give it the exam dates and the hours you can study, and it works out the timetable, the review dates and the breaks. Run it next to an LMS server if you like: one tells you what is assigned, the other tells you how to study it.

Brightspace also writes your due dates into a calendar file, and both of them show the dated events your school posted. What they do not do is turn your exam dates and your study hours into a day by day timetable with spaced repetition dates and pomodoro breaks.

Keywords

People search for a study planner with words like these, so here they are in one place. Revision timetable, exam schedule and spaced repetition dates are on the list, along with the other names for the same jobs.

• study planner mcp
• study planner
• study planner offline
• study-planner-mcp
• study plan mcp
• revision timetable
• revision schedule
• revision plan
• revision planner
• reschedule study plan
• exam schedule
• exam timetable
• exam planner
• exam prep
• exam countdown
• exam study plan
• study schedule
• study timetable
• study calendar
• spaced repetition
• spaced repetition dates
• spaced repetition schedule
• pomodoro
• pomodoro planner
• assignment milestones
• assignment plan
• student planner
• student
• mcp
• mcp server
• model context protocol
• offline

The npm listing uses the same words. If you searched for one of them, install the server and ask for a plan.

How the study plan works

Each day has the hours of that weekday, which is hours_per_day unless you set hours_per_weekday. Those hours are shared across the exams that still need work, weighted by how many hours are left divided by how many days remain, so closer and bigger exams get more time. Study stops the day before each exam. If the hours do not fit, the plan says how many are short instead of pretending. The dates the server works out are plain calendar dates, so time zones never shift a day.

When an exam has topics, the hours the exam gets on a day are split over its topics in proportion to the hours each topic still needs. That way the plan answers which topic to study, not only which exam.

Dates in plain words

Every date the tools take can be written the way you say it. The server reads the date itself, so the day math stays in tested code.

• 2026-12-12 for a date you know exactly.
• Dec 12, December 12 or 12 Dec for a month and a day. Without a year it means the next one that has not passed yet, so asked for in October, Dec 12 means 12 December of that year, and asked for in December it means 12 December of the next year.
• Dec 12 2026 when you want a year of your own.
• today, tomorrow and yesterday.
• in 3 days, in 2 weeks, in 3 months and in 1 year, counted from today. Number words work too, like in two weeks.
• 3 days ago and 2 weeks ago for the days behind you.
• Friday for the coming Friday, next Friday for the Friday of the week after that, and last Friday for the one before.

This works in every date the tools take: the exam dates, start_date, due_date, first_study_date, exam_date, from_date and the date of what_to_study_today.

Dates with a number for the month, like 12/12/2026, are not read, because the order of the numbers is not clear. Write the month as a name, like Dec 12 2026.

Tool call:

{
  "exams": [{ "name": "Networking", "date": "Dec 12 2026", "hours_needed": 6 }],
  "start_date": "2026-12-07",
  "hours_per_day": 2
}

The answer:

Everything fits: 1 exam, 3 study days, 6h

Exams
- Networking on 2026-12-12 sat, 6h planned

Plan from 2026-12-07
- 2026-12-07 mon  Networking 2h  (2h total)
- 2026-12-08 tue  Networking 2h  (2h total)
- 2026-12-09 wed  Networking 2h  (2h total)

Everything fits.

The date 2026-12-12 gives the same plan.

Different hours each day of the week

Study days are not all the same length. hours_per_weekday sets the hours for each weekday, so the plan can give you 2 hours from Monday to Friday and 6 hours on Saturday and Sunday. Weekdays you leave out of the list fall back to hours_per_day, and a weekday with 0 hours is a day off, the same as a day in days_off. Days listed in days_off are always left out. The same list works in export_study_plan_ics and what_to_study_today, so all three tools build the same plan.

Tool call:

{
  "exams": [{ "name": "Networking", "date": "2026-12-12", "hours_needed": 20 }],
  "hours_per_day": 3,
  "hours_per_weekday": [
    { "day": "mon", "hours": 2 },
    { "day": "tue", "hours": 2 },
    { "day": "wed", "hours": 2 },
    { "day": "thu", "hours": 2 },
    { "day": "fri", "hours": 2 },
    { "day": "sat", "hours": 6 },
    { "day": "sun", "hours": 6 }
  ],
  "start_date": "2026-11-30"
}

The answer:

Everything fits: 1 exam, 7 study days, 20h

Exams
- Networking on 2026-12-12 sat, 20h planned

Plan from 2026-11-30
- 2026-11-30 mon  Networking 2h  (2h total)
- 2026-12-01 tue  Networking 2h  (2h total)
- 2026-12-02 wed  Networking 2h  (2h total)
- 2026-12-03 thu  Networking 2h  (2h total)
- 2026-12-04 fri  Networking 2h  (2h total)
- 2026-12-05 sat  Networking 6h  (6h total)
- 2026-12-06 sun  Networking 4h  (4h total)

Everything fits.

Saturday carries the 6 hours, and Sunday gets the 4 hours that are left over.

Hours per topic

Give an exam topics and the plan says which topic to study on each day, not just which exam. The hours of a day are split over the topics of the exam in proportion to the hours each topic still needs, so the topic that needs the most work gets the most time. Leave hours_needed off a topic and the hours of the exam are split evenly over the topics that have no hours of their own.

Tool call:

{
  "exams": [
    {
      "name": "Networking",
      "date": "2026-12-10",
      "topics": [
        { "name": "Routing", "hours_needed": 6 },
        { "name": "Switching", "hours_needed": 4 },
        { "name": "Security", "hours_needed": 2 }
      ]
    }
  ],
  "hours_per_day": 4,
  "start_date": "2026-12-07"
}

The answer:

Everything fits: 1 exam, 3 study days, 12h

Exams
- Networking on 2026-12-10 thu, 12h planned
  - Routing 6h planned
  - Switching 4h planned
  - Security 2h planned

Plan from 2026-12-07
- 2026-12-07 mon  Networking 4h  (4h total)
  - Networking: Routing 2h, Switching 1.5h, Security 0.5h
- 2026-12-08 tue  Networking 4h  (4h total)
  - Networking: Routing 2h, Switching 1.5h, Security 0.5h
- 2026-12-09 wed  Networking 4h  (4h total)
  - Networking: Routing 2h, Switching 1h, Security 1h

Everything fits.

what_to_study_today gives the same topics for one day, so one call tells you what to study today and which part of the exam it belongs to.

Tool call:

{
  "date": "2026-12-08",
  "exams": [
    {
      "name": "Networking",
      "date": "2026-12-10",
      "topics": [
        { "name": "Routing", "hours_needed": 6 },
        { "name": "Switching", "hours_needed": 4 },
        { "name": "Security", "hours_needed": 2 }
      ]
    }
  ],
  "hours_per_day": 4,
  "start_date": "2026-12-07"
}

The answer:

Today 2026-12-08 tue

Study sessions, 4h total
- Networking 4h
  - Routing 2h, Switching 1.5h, Security 0.5h

Next exam: Networking on 2026-12-10 thu, 2 days left.

Example plan

This is a real answer from build_study_plan, copied from a run of the code in this folder. Networking needs 20 hours by Dec 12 and Scripting needs 16 hours by Dec 15, with 3 hours a day and no study on Sundays. Passing start_date is what makes the dates repeatable.

Tool call:

{
  "exams": [
    { "name": "Networking", "date": "2026-12-12", "hours_needed": 20 },
    { "name": "Scripting", "date": "2026-12-15", "hours_needed": 16 }
  ],
  "hours_per_day": 3,
  "days_off": ["sun"],
  "start_date": "2026-11-30"
}

The answer:

Everything fits: 2 exams, 12 study days, 36h

Exams
- Networking on 2026-12-12 sat, 20h planned
- Scripting on 2026-12-15 tue, 16h planned

Plan from 2026-11-30
- 2026-11-30 mon  Networking 2h, Scripting 1h  (3h total)
- 2026-12-01 tue  Networking 2h, Scripting 1h  (3h total)
- 2026-12-02 wed  Networking 2h, Scripting 1h  (3h total)
- 2026-12-03 thu  Networking 2h, Scripting 1h  (3h total)
- 2026-12-04 fri  Networking 1.5h, Scripting 1.5h  (3h total)
- 2026-12-05 sat  Networking 2h, Scripting 1h  (3h total)
- 2026-12-07 mon  Networking 2h, Scripting 1h  (3h total)
- 2026-12-08 tue  Networking 1.5h, Scripting 1.5h  (3h total)
- 2026-12-09 wed  Networking 2h, Scripting 1h  (3h total)
- 2026-12-10 thu  Networking 1.5h, Scripting 1.5h  (3h total)
- 2026-12-11 fri  Networking 1.5h, Scripting 1.5h  (3h total)
- 2026-12-12 sat  Scripting 3h  (3h total)

Everything fits.

Sundays are skipped, and Networking stops on Dec 11 because studying stops the day before each exam, so Dec 12 is Scripting only.

Calendar file

export_study_plan_ics takes the same arguments as build_study_plan and answers with a complete .ics file instead of plain text. Save the answer as plan.ics and open it, or import it in Google Calendar or Apple Calendar. Every study session becomes an all day event marked free, every exam becomes an all day event marked busy, and include_exams: false gives you the study sessions only. Each event carries a UID built from its date and exam name, and the dates are written as plain calendar dates, so no time zone moves an event to another day.

Tool call:

{
  "exams": [{ "name": "Networking", "date": "2026-12-12", "hours_needed": 6 }],
  "start_date": "2026-12-07",
  "hours_per_day": 2,
  "days_off": ["sun"]
}

These are the first lines of the file, copied from a run. Two more study events and one exam event follow in the same shape, and DTSTAMP is the moment of the export, so yours will differ.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//AnonymousOnyx22//Study Planner MCP//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Study plan
BEGIN:VEVENT
UID:2026-12-07-networking-study@study-planner-mcp
DTSTAMP:20261021T022919Z
DTSTART;VALUE=DATE:20261207
DTEND;VALUE=DATE:20261208
SUMMARY:Study: Networking 2h
DESCRIPTION:Networking\, 2h of study. Day total 2h. Exam on 2026-12-12 sat.
TRANSP:TRANSPARENT
END:VEVENT

What to study today

what_to_study_today answers one day in one call. It merges the study sessions your plan gives for that day with the spaced repetition reviews that are due that day or are late. Pass the same exams and hours you use in build_study_plan, and the topics you are reviewing with the day you first studied each one. Leave date out and it uses today's date. Pass start_date if your plan already has a first day, so the sessions match the plan you made earlier.

Tool call:

{
  "date": "2026-11-30",
  "exams": [{ "name": "Networking", "date": "2026-12-12", "hours_needed": 12 }],
  "hours_per_day": 2,
  "reviews": [{ "topic": "Routing", "first_study_date": "2026-11-27" }]
}

The answer:

Today 2026-11-30 mon

Study sessions, 2h total
- Networking 2h

Reviews due today
- Routing, 2nd review

Reviews to catch up
- Routing, 1st review, 2 days late (due 2026-11-28)

Next reviews
- Routing on 2026-12-04 fri, 3rd review

Next exam: Networking on 2026-12-12 sat, 12 days left.

Exam countdown

exam_countdown answers whether you are on track for an exam. It gives the days left, the number of study days left after days off and weekdays with 0 hours, the hours the exam still needs, the hours to put in on each study day and a plain verdict. It uses the same hours_per_day, hours_per_weekday and days_off as the plan tools, so the verdict matches the plan they build. Pass from_date to count from a fixed day.

Tool call:

{
  "exams": [{ "name": "Networking", "date": "2026-12-12", "hours_needed": 20 }],
  "from_date": "2026-11-30",
  "hours_per_day": 2,
  "days_off": ["sun"]
}

The answer:

Exam countdown from 2026-11-30 mon

Networking, exam 2026-12-12 sat
- 12 days left, 11 study days left
- 20h still needed, 1.8h per study day
- On track: 20h fits in 11 study days at your hours.

If the hours do not fit, the last line says Behind by the hours short, so you know how much time to add or how many hours to lower.

Reschedule missed days

reschedule_missed_days is for the week that did not go to plan. Give each exam the hours you have already done with hours_done, say which day you are starting again with start_date, and it takes the done hours off each exam before it spreads the hours left over the days that remain. It uses the same hours_per_day, hours_per_weekday and days_off as build_study_plan, and an exam with topics takes the done hours off its topics in proportion to their hours. Use it when you need to reschedule study plan hours after a break, without counting the same work twice.

Tool call:

{
  "exams": [{ "name": "Networking", "date": "2026-12-12", "hours_needed": 10, "hours_done": 4 }],
  "hours_per_day": 2,
  "start_date": "2026-12-09"
}

The answer:

Exams
- Networking on 2026-12-12 sat, 4h done, 6h left

Rescheduled from 2026-12-09
- 2026-12-09 wed  Networking 2h  (2h total)
- 2026-12-10 thu  Networking 2h  (2h total)
- 2026-12-11 fri  Networking 2h  (2h total)

Everything fits.

The four hours already done come off the ten the exam needs, so the repaired plan starts on Dec 9 with six hours left to study.

Next review date

next_review_dates gives one date, the next review for one topic, instead of the whole schedule. It counts from the day you first studied the topic, and it skips any review that falls on or after the exam. The answer counts the reviews that have already passed. Pass from_date to say which day to count from, so the answer is repeatable. Use make_spaced_repetition_schedule when you want every review date.

Tool call:

{
  "topic": "Routing",
  "first_study_date": "2026-11-27",
  "exam_date": "2026-12-12",
  "from_date": "2026-11-29"
}

The answer:

Next review for "Routing": 2026-11-30 mon, the 2nd review, in 1 day.
1 review has passed.

The routing was first studied on Nov 27, so the first review fell on Nov 28 and has passed. The next one is Nov 30, and the review on Dec 27 is left out because it falls after the exam on Dec 12.

Troubleshooting

When a tool call fails, the server sends back a short message that says what to change. These are the ones people hit most, with the text as it appears and the fix.

A date is not understood

Invalid arguments for tool make_study_plan: exam_date must be a date, got "in a few weeks". "in a few weeks" is not a date I can read. Use 2026-12-12, or plain text like Dec 12, next Friday or in 3 weeks. Write the month as a name, like Dec 12 2026, when the day comes first.

Plain text dates like in 3 weeks, next Friday and Dec 12 work, but the count has to be one number or one number word, so in a few weeks does not. Give a number (in 3 weeks) or a full date like 2026-12-12. If a message says a month or weekday could be two names, write it out in full.

The exam is not after the start date

Networking is on 2026-10-01, which is not after the start date 2026-11-01.

The exam date is today or already past, so there is no day left to study. Check the year, because a date written as Oct 1 means the next Oct 1 but 2026-10-01 is taken as written. If you are rebuilding a plan after missing days, use reschedule_missed_days instead.

Hours per day is zero

Invalid arguments for tool make_study_plan: hours_per_day must be greater than 0; try hours_per_day: 3

hours_per_day has to be above 0 and at most 16. To skip a day, leave it out with days_off: ["sun"], or give a weekday 0 hours in hours_per_weekday, like [{day: "sun", hours: 0}].

Topic hours do not match the exam

The exam Networking needs 6h but its topics add up to 5h. Make the exam hours match the topics, or leave hours_needed out of the exam.

When an exam has topics, either give hours to every topic and leave hours_needed off the exam, or give hours_needed on the exam and let the topics share it evenly.

The server does not show up in your app

Run npm run build if you installed from source, then restart the app after editing its config. The Install section above has the exact config for each app.

Development

npm install
npm run build
npm test
npm run demo

npm run demo runs after the build and prints a sample plan for two exams, the what_to_study_today answer for one day and the first lines of the .ics file. It uses fixed dates, so the output is the same each time.

Pass start_date in tools to get repeatable results. The tests call every tool through a real MCP client, so they need no account or network.

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

FAQ

How many hours a day before my exam?

You give the hours you can study on each day. The plan spreads work by urgency, so if time is tight it concentrates more near the exam. If there is not enough time, the plan gives a warning.

How do I space out revision?

Use make_spaced_repetition_schedule for a topic to get review dates at expanding intervals. You can also use next_review_dates for just the next one. Dates on or after the exam are marked to skip.

Is there a study planner offline?

Yes. This server runs on your computer with no account, no login and no internet needed. All date math runs locally.

What should I study today?

Use what_to_study_today with your exam dates and hours or with a plan. It lists sessions for today and any spaced repetition reviews due or late.

Can I add the plan to my calendar?

Yes. Use export_study_plan_ics to get an .ics file you can import into Google Calendar or Apple Calendar.