Student Progress Tracker Server

MCP server for AI-powered student progress tracking and learning analytics. Connects to Claude Desktop or Claude Code to give AI assistants the ability to manage students, track assessments, calculate mastery levels, identify learning gaps, and recommend focus areas.

Python MCP License: MIT

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external tools and data sources. This server exposes student progress tracking as MCP tools that Claude can call directly during conversations.

Features

• Student profiles - Create and manage student records with grade levels
• Course enrollment - Organize students into courses with topics
• Assessment tracking - Record tests, quizzes, homework, and practice results
• Mastery levels - Automatic topic mastery calculation from question-level data
• Learning gap analysis - Identify topics below threshold with severity ratings
• Focus recommendations - Prioritized study suggestions based on trends
• Class analytics - Grade distribution and topic performance across a class
• Question-level telemetry - Track correctness, time, difficulty, and Bloom's level per question

Quick Start

Install

git clone https://github.com/woodstocksoftware/student-progress-tracker.git
cd student-progress-tracker
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "student-progress": {
      "command": "/absolute/path/to/student-progress-tracker/venv/bin/python",
      "args": ["/absolute/path/to/student-progress-tracker/run_server.py"]
    }
  }
}

Restart Claude Desktop. The tools will appear automatically.

Configure Claude Code

Add to your project's .mcp.json or global settings:

{
  "mcpServers": {
    "student-progress": {
      "command": "/absolute/path/to/student-progress-tracker/venv/bin/python",
      "args": ["/absolute/path/to/student-progress-tracker/run_server.py"]
    }
  }
}

Try It

You: Create a student named Alice in 9th grade
You: Create a course called Algebra I in Mathematics
You: Enroll Alice in Algebra I
You: Create a topic "Linear Equations" in the Algebra course
You: Record Alice's quiz: 85 out of 100
You: What are Alice's learning gaps?
You: What should Alice focus on next?

Tool Reference

Student Management

create_student

Create a new student record.

Parameter	Type	Required	Description
name	string	Yes	Student's full name
email	string	No	Email address
grade_level	string	No	e.g., "9th Grade", "College Freshman"

Create a student named Alice Johnson, email [email protected], in 9th grade

list_students

List all students, optionally filtered by course.

Parameter	Type	Required	Description
course_id	string	No	Filter by course enrollment

get_student_profile

Comprehensive profile with courses, statistics, and recent assessments.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID

Course Management

create_course

Create a new course.

Parameter	Type	Required	Description
name	string	Yes	e.g., "Algebra I", "Biology 101"
subject	string	Yes	e.g., "Mathematics", "Science"
grade_level	string	No	Target grade level
question_bank_id	string	No	Link to Question Bank MCP

list_courses

List all courses with enrolled student counts.

enroll_student

Enroll a student in a course.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID
course_id	string	Yes	The course ID

create_topic

Add a topic within a course for mastery tracking.

Parameter	Type	Required	Description
course_id	string	Yes	The course ID
name	string	Yes	e.g., "Linear Equations"
weight	float	No	Importance weight (default 1.0)

list_topics

List all topics in a course.

Parameter	Type	Required	Description
course_id	string	Yes	The course ID

Assessment & Results

create_assessment

Create a test, quiz, homework, or practice assessment.

Parameter	Type	Required	Description
course_id	string	Yes	The course ID
name	string	Yes	e.g., "Chapter 3 Quiz"
assessment_type	string	Yes	test, quiz, homework, or practice
total_points	float	Yes	Total points possible
total_questions	int	Yes	Number of questions
time_limit_minutes	int	No	Time limit in minutes

record_assessment_result

Record a student's assessment result with optional question-level data.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID
assessment_id	string	Yes	The assessment ID
points_earned	float	Yes	Points earned
points_possible	float	Yes	Total points possible
time_spent_minutes	int	No	Time spent in minutes
question_results	list	No	Per-question data (see below)

Each item in question_results:

{
  "question_id": "q1",
  "topic_id": "topic-abc123",
  "is_correct": true,
  "time_spent_seconds": 45,
  "difficulty": 0.5,
  "bloom_level": "application"
}

Analytics & Recommendations

get_topic_mastery

View mastery levels by topic with trend indicators.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID
course_id	string	No	Filter by course

get_learning_gaps

Identify topics below a mastery threshold.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID
threshold	float	No	Mastery threshold % (default 70)

get_student_history

Question-level performance history.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID
topic_id	string	No	Filter by topic
limit	int	No	Max records (default 20)

get_class_analytics

Class-wide performance overview with grade distribution and topic analysis.

Parameter	Type	Required	Description
course_id	string	Yes	The course ID

recommend_focus_areas

Personalized study recommendations prioritized by trend and mastery level.

Parameter	Type	Required	Description
student_id	string	Yes	The student ID

Data Model

Students ──── Enrollments ──── Courses ──── Topics
   │                              │           │
   │                              │           │
   └──── Assessment Results ──── Assessments  │
              │                               │
              │                               │
         Question History ──── Topic Mastery ─┘

Tables

Table	Purpose
students	Student records (id, name, email, grade_level)
courses	Courses with subject and optional question bank link
enrollments	Student-course relationships with status
topics	Hierarchical topics within courses with weights
assessments	Tests, quizzes, homework, practice
assessment_topics	Which topics an assessment covers
assessment_results	Student scores with JSON question-level data
topic_mastery	Cached mastery level (0-1), trend, question stats
question_history	Per-question correctness, timing, difficulty, Bloom's level

Mastery Calculation

Mastery is calculated as questions_correct / questions_attempted per topic. Trends are detected by comparing recent accuracy to overall mastery:

• Improving - Recent accuracy > mastery + 10%
• Stable - Within 10% of mastery
• Declining - Recent accuracy < mastery - 10%

Usage Examples

Track a Student's Math Mastery Over Time

1. Create a student and course
2. Add topics: Linear Equations, Quadratic Equations, Polynomials
3. Record quiz results with question_results linking to topics
4. View mastery: "Show me Alice's topic mastery for Algebra I"
5. Check gaps: "What are Alice's learning gaps?"
6. Get recommendations: "What should Alice focus on next?"

Monitor a Class

1. Create a course with multiple enrolled students
2. Record assessment results for each student
3. View analytics: "Show class analytics for Algebra I"
4. See grade distribution and struggling topic areas

Architecture

Claude (Desktop/Code)
    │
    │ MCP Protocol (stdio)
    │
    ▼
┌─────────────────────────────┐
│  server.py (FastMCP)        │
│  15 tools with @mcp.tool()  │
│  Markdown response format   │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  database.py (SQLite)       │
│  10 tables, auto-init       │
│  Foreign keys + indexes     │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  data/student_progress.db   │
│  Local file (gitignored)    │
└─────────────────────────────┘

Key design decisions:

• FastMCP decorators for tool registration with auto-generated JSON schemas
• stdio transport for communication with Claude
• SQLite for zero-config local persistence
• Markdown responses with emoji indicators for readability in chat
• UUID-prefixed IDs (stu-, course-, topic-, assess-, result-) for clarity
• JSON question_results for flexible per-question data storage

Integration with Question Bank MCP

Designed to compose with Question Bank MCP:

Question Bank MCP              Student Progress Tracker
┌───────────────────┐          ┌───────────────────────┐
│ Questions         │          │ Students              │
│ Topics            │◄────────►│ Enrollments           │
│ Difficulty levels │          │ Assessment Results    │
│ Bloom's taxonomy  │          │ Topic Mastery         │
└───────────────────┘          └───────────────────────┘

Link them via question_bank_id when creating a course.

Testing

source venv/bin/activate
pip install pytest
pytest tests/ -v

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes with type hints and docstrings
4. Run linting: ruff check src/
5. Run tests: pytest tests/ -v
6. Commit and open a pull request

License

MIT

---

Part of the Ed-Tech MCP Suite by Jim Williams | GitHub

MCP Server	Purpose
Question Bank	Create and manage questions
Student Progress	Track performance and mastery