exam-prep-mcp

AI-powered exam preparation MCP server with FSRS-5 spaced repetition

Overview

exam-prep-mcp is a Model Context Protocol (MCP) server that brings adaptive, science-backed exam preparation into your AI assistant workflow. It uses the FSRS-5 spaced repetition algorithm to schedule reviews at optimal intervals — you study smarter, not harder.

Features

• FSRS-5 Spaced Repetition — Cards are scheduled based on your performance and forgetting curves
• 50+ Real Practice Questions — Accurate questions with detailed explanations across AP and SAT subjects
• Study Plan Generator — Personalized day-by-day schedule based on your exam date and level
• Mock Exams — Full-length timed practice exams with grade estimates
• Readiness Score — Track your preparation progress with a 0-100 readiness score
• Weak Area Detection — Automatically identifies topics that need more focus
• Multiple Exam Types — AP Biology, AP Chemistry, AP US History, SAT Math, MCAT, LSAT, GRE, and more

Installation

Global install (recommended)

npm install -g @gonzih/exam-prep-mcp

Run without installing

npx @gonzih/exam-prep-mcp

MCP Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "exam-prep": {
      "command": "exam-prep-mcp"
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "exam-prep": {
      "command": "npx",
      "args": ["-y", "@gonzih/exam-prep-mcp"]
    }
  }
}

Custom database path

{
  "mcpServers": {
    "exam-prep": {
      "command": "exam-prep-mcp",
      "env": {
        "EXAM_PREP_DB": "/path/to/your/study.sqlite"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | EXAM_PREP_DB | ~/.exam-prep/study.sqlite | Path to SQLite database file |

Tools

1. set_exam

Configure an exam for a student profile. Seeds question cards and generates a personalized study plan.

Parameters:

• profileId (string, required) — Unique student identifier (e.g., "alice", "student-001")
• examType (string, required) — Exam to prepare for (see Supported Exams below)
• examDate (string, required) — Exam date in YYYY-MM-DD format
• currentLevel (string, required) — "beginner", "intermediate", or "advanced"

Returns: Study plan, topics identified, days remaining, seeded card count

2. get_daily_session

Get today's personalized practice questions based on FSRS spaced repetition scheduling.

Parameters:

• profileId (string, required) — Student profile ID

Returns: 10-15 questions with card IDs, topics, question text, choices (for MC), estimated time, focus areas

3. answer_question

Submit an answer to a practice question. Evaluates correctness, applies FSRS scheduling, and detects weak areas.

Parameters:

• profileId (string, required) — Student profile ID
• cardId (string, required) — Card ID from get_daily_session or start_mock_exam
• answer (string, required) — Student's answer ("A", "B", "C", "D" for multiple choice; text for others)
• rating (1-4, optional) — Manual difficulty rating: 1=Again, 2=Hard, 3=Good, 4=Easy

Returns: Correct/incorrect, correct answer, explanation, next review date, weak area alert if applicable

4. start_mock_exam

Begin a timed full-length practice exam simulating real exam conditions.

Parameters:

• profileId (string, required) — Student profile ID

Returns: Session ID, all exam questions, time limit in minutes, instructions

5. submit_mock_exam

Submit all answers for a completed mock exam and receive detailed scoring and analysis.

Parameters:

• sessionId (string, required) — Session ID from start_mock_exam
• answers (array, required) — Array of { cardId, answer } objects

Returns: Score, grade estimate, topic breakdown, weak/strong topics, readiness score update, recommendation

6. get_readiness

Get a comprehensive readiness report with your current score, grade estimate, performance trend, and recommendation.

Parameters:

• profileId (string, required) — Student profile ID

Returns: 0-100 readiness score, strong/weak topics, coverage percent, trend (improving/declining/stable), grade estimate, recommendation

7. get_weak_areas

Identify topics with accuracy below 60% that need focused study.

Parameters:

• profileId (string, required) — Student profile ID

Returns: Ranked list of weak topics with accuracy and attempt counts, suggested focus plan

Supported Exam Types

| Exam Type | Description | Questions | Time Limit | |-----------|-------------|-----------|------------| | AP_Biology | AP Biology | 60 | 170 min | | AP_Chemistry | AP Chemistry | 60 | 190 min | | AP_US_History | AP US History | 55 | 205 min | | AP_World_History | AP World History | 55 | 205 min | | AP_Physics | AP Physics | 50 | 180 min | | AP_Calculus | AP Calculus AB/BC | 45 | 195 min | | AP_Statistics | AP Statistics | 40 | 180 min | | AP_English | AP English Language | 45 | 215 min | | AP_Economics | AP Micro/Macro Economics | 60 | 130 min | | SAT_Math | SAT Math section | 44 | 70 min | | SAT_Reading | SAT Reading section | 52 | 65 min | | SAT_Writing | SAT Writing section | 44 | 35 min | | MCAT | Medical College Admissions | 230 | 375 min | | LSAT | Law School Admissions | 100 | 175 min | | GRE | Graduate Record Examination | 80 | 225 min |

Example Conversation

Scenario: Student has AP Chemistry exam in 3 weeks

Student: I have my AP Chemistry exam on May 15th. I'm currently at an intermediate level. Can you set me up?

Claude: I'll set up your AP Chemistry exam prep right away!

[calls set_exam with profileId="student", examType="AP_Chemistry", examDate="2025-05-15", currentLevel="intermediate"]

Great! I've configured your AP Chemistry prep:

• 21 days until your exam
• 10 topics identified: Atomic Structure, Chemical Bonding, Stoichiometry, Gas Laws, Thermodynamics, Chemical Equilibrium, Acids and Bases, Electrochemistry, Kinetics, Nuclear Chemistry
• 48 practice cards seeded into your study queue
• Weekly goal: Master 3-4 topics per week

Student: What should I study today?

Claude: [calls get_daily_session]

Today's session (12 questions, ~30 min):

Focus areas: Stoichiometry, Gas Laws, Acids and Bases

1. [Stoichiometry] How many grams of H₂O are produced when 4.0g of H₂ reacts completely with excess O₂?
2. [Gas Laws] A gas occupies 2.0 L at 300K and 1.0 atm. What volume at 600K and 2.0 atm? ...

Student: For question 1, I think it's 36 grams.

Claude: [calls answer_question with answer="36 g"]

Correct! Well done.

36 g is right. 2H₂ + O₂ → 2H₂O. Moles H₂ = 4.0g / 2.0g/mol = 2.0 mol. From stoichiometry, 2.0 mol H₂O × 18 g/mol = 36 g.

Next review: in 3 days

Student: Let's do a mock exam!

Claude: [calls start_mock_exam]

Starting your AP Chemistry mock exam:

• 60 questions
• 190 minutes time limit
• Answer all questions, then use submit_mock_exam when done.

Student: How ready am I overall?

Claude: [calls get_readiness]

Readiness Score: 67/100

• Estimated AP Score: 4/5 (Well Qualified)
• Topics mastered: Chemical Bonding, Atomic Structure
• Weak areas: Electrochemistry (40%), Thermodynamics (50%)
• Trend: Improving
• 21 days remaining — excellent time to close the gaps!

Recommendation: Focus on Electrochemistry and Thermodynamics this week. You're on track for a 4!

How FSRS Works

FSRS-5 (Free Spaced Repetition Scheduler) is a state-of-the-art algorithm that models human memory:

• Stability (S): How long you'll remember something (in days)
• Difficulty (D): How hard the material is for you (1-10 scale)
• Retrievability (R): Probability you can recall it right now (0-1)

After each answer, the algorithm calculates your next optimal review date. Cards you find easy get longer intervals; cards you struggle with come back sooner. This minimizes total study time while maximizing retention.

Development

git clone https://github.com/gonzih/exam-prep-mcp
cd exam-prep-mcp
npm install
npm run dev     # Run with tsx (no build needed)
npm run build   # Compile TypeScript
npm start       # Run compiled version

License

MIT © Gonzih