[RFC] MCP Server for OpenedX LMS — v1 Analytics & Data Query

Summary

Add a Model Context Protocol (MCP) server that allows AI assistants (e.g. Claude) to answer data-specific questions against live or reporting-database LMS data in natural language.

Motivation

Operators, course teams, and analysts regularly need answers to questions like:

• "How many learners enrolled in Course X last week?"
• "Which problem in Course Y has the lowest success rate?"
• "Show me the grade distribution for a given subsection."

Today those answers require writing custom queries, navigating multiple admin dashboards, or waiting on a data team. An MCP server exposes structured, pre-validated tools so that Claude (or any MCP-compatible client) can answer these questions directly against LMS data — without the user needing to know the underlying schema.

Proposal

A standalone Python MCP server that:

• Connects to a MySQL read replica (or dedicated reporting DB) via a read-only service account
• Exposes a focused set of tools covering enrollment, grades, certificates, and learner progress
• Validates and sanitizes all inputs; enforces per-query timeouts
• Returns structured JSON that the AI client interprets and summarizes for the user

Architecture

AI assistant (MCP client, e.g. Claude)
        │
        ▼
openedx-mcp-server  (Python, mcp SDK)
        │   read-only service account
        ▼
  MySQL read replica  ─── or ───  reporting DB (e.g. Aspects / data warehouse)

Safety constraints:

• DB user granted SELECT only — no writes possible at the DB level
• No raw SQL passthrough; all queries are pre-written and parameterized
• Per-query timeout enforced (default 5 s)
• Aggregate tools return counts only; per-learner tools require explicit include_pii=true and the caller is responsible for access control

V1 Scope

In scope: read-only queries against MySQL for enrollment, grades, certificates, and course metadata.

Out of scope for v1: writes of any kind, MongoDB queries, real-time event streams, unauthenticated PII export, data warehouse / Aspects integration (v2).

Tools

Tool	Description	Key tables
get_enrollment_stats	Enrollment counts and trends for a course, filtered by date range and/or enrollment mode	student_courseenrollment
get_active_learners	DAU / WAU / MAU counts for a course	student_courseenrollment, courseware_studentmodule
get_grade_distribution	Grade histogram per course or subsection	grades_persistentcoursegrade, grades_persistentsubsectiongrade
get_problem_stats	Per-problem success rates, attempt counts, difficulty ranking	courseware_studentmodule
get_learner_progress	Unit-level completion and scores for a single learner in a course	courseware_studentmodule, grades_persistentsubsectiongrade
get_certificate_stats	Certificates issued and passing-threshold breakdown	certificates_generatedcertificate
list_active_courses	Running courses for an org with enrollment counts	student_courseenrollment, course_overviews_courseoverview

Task List

Setup

• Decide home: standalone repo vs. tools/mcp/ subdirectory in this repo
• Scaffold MCP server (Python, mcp SDK)
• Read-only MySQL connection + connection pooling
• Query timeout enforcement and error handling

Tools

• get_enrollment_stats
• get_active_learners
• get_grade_distribution
• get_problem_stats
• get_learner_progress
• get_certificate_stats
• list_active_courses

Quality

• Unit tests for each tool (mock DB)
• Integration test against a Tutor dev environment
• README / setup guide (how to point at a read replica, configure credentials)

Additional Info

• MCP spec: https://modelcontextprotocol.io
• Python MCP SDK: https://github.com/modelcontextprotocol/python-sdk
• OpenedX Aspects (event data warehouse) is a natural v2 backend: https://docs.openedx.org/projects/openedx-aspects

No repository files or test entry points are named. Start by resolving whether the server belongs in a standalone repository or tools/mcp/, then review the Python MCP SDK and the listed LMS tables; done requires the seven read-only tools, timeout and input-safety constraints, mocked unit tests, a Tutor integration test, and setup documentation.