Skip to main content
Glama
penn-course-mcp

penn-course-mcp

by grantdehoog

penn-course-mcp

An MCP server for University of Pennsylvania course planning. It is built on the public Penn Courses API (the same backend behind Penn Course Plan and Penn Course Review), so the catalog, ratings, and schedule data are live.

With it, an MCP client (Claude Desktop, Claude Code, or any other) can search the course catalog, inspect sections and meeting times, read ratings and reviews, check a set of sections for time conflicts, assemble a weekly schedule, and save that schedule back to a Penn Course Plan account.

The server works with no configuration against the public API. Setting a session cookie additionally unlocks detailed Penn Course Review breakdowns and the schedule-write tools. It runs over stdio for local clients, or streamable HTTP when hosted.

Tools

Tool

What it does

get_current_semester

Active term code (e.g. 2026C) and review-auth status

search_courses

Search the catalog by code or keyword; returns summaries and ratings

get_course_details

Full course info: description, prereqs, attributes, sections, meeting times

list_course_sections

Sections with formatted meeting times and instructors; filter by status or activity

get_course_ratings

Public aggregate ratings (quality, difficulty, workload)

get_course_reviews

Detailed PCR reviews when authenticated; falls back to aggregates otherwise

find_courses_by_attribute

Courses carrying a given attribute or Gen-Ed code

find_courses_by_requirement

Courses fulfilling a requirement (by code or name)

check_schedule_conflicts

Detect time conflicts among a set of section ids

build_schedule

Weekly grid, total credits, conflicts, and missing-companion warnings

compare_courses

Side-by-side ratings, difficulty, workload, and prereqs

recommend_courses

Search and rank by quality, difficulty, or workload

list_schedules

List the saved schedules in your Penn Course Plan account (auth)

save_schedule

Write a schedule to your Penn Course Plan account so it shows on the site (auth)

delete_schedule

Delete a saved Penn Course Plan schedule by id (auth)

Course codes look like CIS-1200; section ids look like CIS-1200-001.

Related MCP server: Brown Courses MCP Server

Installation

uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"

Running

# stdio (default), for Claude Desktop / Claude Code
penn-course-mcp

# streamable HTTP at http://127.0.0.1:8000/mcp
penn-course-mcp --transport http --port 8000

# development server / MCP Inspector
fastmcp dev src/penn_course_mcp/server.py

Client configuration

Add the server to your MCP client config (for Claude Desktop, this is claude_desktop_config.json):

{
  "mcpServers": {
    "penn-course": {
      "command": "uvx",
      "args": ["penn-course-mcp"],
      "env": {
        "PENN_COURSES_SESSION_COOKIE": ""
      }
    }
  }
}

Use "command": "penn-course-mcp" instead of uvx if you installed the package into a virtualenv that is on your PATH.

Configuration

All environment variables are optional (see .env.example):

Variable

Default

Purpose

PENN_COURSES_BASE_URL

https://penncoursereview.com

API base URL

PENN_COURSES_SEMESTER

current

Default semester (current auto-resolves)

PENN_COURSES_CACHE_TTL

3600

Cache TTL (seconds) for catalog and detail data

PENN_COURSES_TIMEOUT

20.0

HTTP timeout (seconds)

PENN_COURSES_USER_AGENT

penn-course-mcp/<ver>

Sent with every request

PENN_COURSES_SESSION_COOKIE

(unset)

Enables detailed reviews and schedule writes (see below)

PENN_COURSES_TRANSPORT / --transport

stdio

stdio or http

PENN_COURSES_HOST / --host

127.0.0.1

HTTP host

PENN_COURSES_PORT / --port

8000

HTTP port

Detailed reviews and schedule writes

The public API exposes aggregate ratings (course and instructor quality, difficulty, and work required) without authentication. The detailed per-instructor Penn Course Review breakdowns, and the schedule-write tools, require a logged-in Penn session. To enable them, log in to penncoursereview.com, copy your session cookie, and set:

export PENN_COURSES_SESSION_COOKIE="sessionid=...; csrftoken=..."

get_course_reviews falls back to the public aggregate ratings when no cookie is set, so it never errors. The schedule-write tools (list_schedules, save_schedule, delete_schedule) read and modify a real Penn Course Plan account, so they always need the cookie. Writes also need the csrftoken value, since Django enforces CSRF on unsafe methods. save_schedule creates a new schedule by default; pass an existing schedule_id (from list_schedules) to overwrite one instead.

The read-only catalog and rating tools never modify your account. Only the three schedule tools do.

Claude skill

This repository ships an optional Agent Skill at .claude/skills/penn-course-planning. It gives Claude guidance on using the tools well, including normalizing course codes (CIS 120 to CIS-1200), reading the rating scales, and choosing the right tool for schedule and requirement questions. It activates automatically when you use Claude Code in this repository. To make it available everywhere, copy it into your user skills folder:

cp -R .claude/skills/penn-course-planning ~/.claude/skills/

Development

uv pip install -e ".[dev]"
pytest      # pure planning logic, mocked client, and tool tests
flake8      # style, import order (isort), and quote checks
black .     # formatter

The planning logic in src/penn_course_mcp/planning.py is pure and network-free, so the schedule-conflict detection, time formatting, and comparison are covered by unit tests without hitting the API.

Notes

  • Meeting times use Penn's HH.MM encoding (10.15 is 10:15, 15.3 is 15:30). The server renders them as readable HH:MM ranges.

  • Day codes are M, T, W, R, F, where R is Thursday.

  • Back-to-back meetings, where one ends exactly as the next begins, are not counted as conflicts.

  • This is an unofficial tool that consumes the public Penn Courses API. It caches responses and caps concurrency; please use it respectfully.

License

MIT

Available Tools

15 tools
build_scheduleA

Assemble a weekly schedule from section ids: total credits, a day-by-day grid, time conflicts, and warnings for missing required companion sections.

Inputs: sections (required), semester. Returns: object

check_schedule_conflictsA

Check a set of section ids (e.g. ['CIS-1200-001','MATH-1400-002']) for time conflicts. Returns the clashing meetings in human-readable form.

Inputs: sections (required), semester. Returns: object

compare_coursesB

Compare courses side by side on ratings, difficulty, workload, credits, and prerequisites. Accepts a list of course codes (e.g. ['CIS-1200','CIS-1600']).

Inputs: course_codes (required), semester. Returns: object

delete_scheduleA

Delete a saved Penn Course Plan schedule by its id (requires auth).

Use list_schedules to find the id first. This permanently removes the schedule from your Penn Course Plan account.

Inputs: schedule_id (required). Returns: object

find_courses_by_attributeA

Find courses carrying a given attribute (e.g. 'EUMS', 'MFR', a Gen-Ed code).

match='code' requires an exact attribute-code match; match='description' does a substring search across codes and descriptions. Supply prefilter_query to narrow the candidate set first (faster, smaller payload).

Inputs: attribute (required), limit, match, semester, +1 more. Returns: object

find_courses_by_requirementB

Find courses fulfilling a requirement (pre-NGSS requirement code or name).

Substring-matches against course attributes and pre-NGSS requirement codes/names.

Inputs: requirement (required), limit, semester. Returns: object

get_course_detailsC

Get full details for a course: description, prerequisites, attributes, crosslistings, aggregate ratings, and all sections with meeting times.

Inputs: course_code (required), semester. Returns: object

get_course_ratingsB

Return the public aggregate ratings for a course (always available).

Includes course_quality, instructor_quality, difficulty, and work_required.

Inputs: course_code (required), semester. Returns: object

get_course_reviewsA

Get detailed Penn Course Review breakdowns for a course.

When an authenticated session cookie is configured this returns the full per-instructor review data. Otherwise it gracefully falls back to the public aggregate ratings and reports an unauthenticated status (never errors).

Inputs: course_code (required). Returns: object

get_current_semesterA

Return the active semester and whether detailed reviews are enabled.

Useful as a first call to learn the current term code (e.g. '2026C') and the server's review-auth status.

Inputs: no named parameters. Returns: object

list_course_sectionsA

List a course's sections with formatted meeting times and instructors.

open_only keeps only sections whose status is open; activity filters by type (e.g. 'LEC', 'REC', 'LAB').

Inputs: course_code (required), activity, semester, open_only. Returns: object

list_schedulesA

List the saved schedules in your Penn Course Plan account (requires auth).

Returns each schedule's id, name, semester, and the section ids it contains — handy for finding a schedule_id to update or delete.

Inputs: no named parameters. Returns: object

recommend_coursesA

Search and rank courses by a quality metric.

sort_by is one of: 'course_quality', 'instructor_quality', 'recommendation_score' (higher is better), or 'difficulty' / 'work_required' (lower is better, for finding lighter courses).

Inputs: query (required), limit, sort_by, semester. Returns: object

save_scheduleA

Save a schedule to your Penn Course Plan account so it appears on the website.

Creates a new schedule named name containing the given sections (full section ids like 'CIS-1200-001'). Pass an existing schedule_id to overwrite that schedule instead of creating a new one. Writes to your live Penn account and requires PENN_COURSES_SESSION_COOKIE (sessionid + csrftoken).

Inputs: name (required), sections (required), semester, schedule_id. Returns: object

search_coursesA

Search the course catalog by code or keyword (e.g. 'CIS-1200' or 'ethics').

Returns lightweight course summaries including aggregate ratings. semester defaults to the current term.

Inputs: query (required), limit, semester. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a distinct purpose: searching, retrieving details, listing sections, getting ratings/reviews, finding by attribute/requirement, checking conflicts, building schedules, comparing, recommending, and managing saved schedules. No overlapping functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., search_courses, get_course_details, build_schedule). The verbs vary (search, get, list, find, check, build, compare, recommend, save, delete) but are descriptive and predictable.

    Tool Count5/5

    15 tools cover the full lifecycle of course exploration and schedule planning without being excessive. Each tool serves a clear purpose in the domain, and the count is appropriate for a comprehensive course management MCP.

    Completeness5/5

    The tool surface covers all major operations: course search, details, ratings, reviews, attribute/requirement filtering, schedule building, conflict checking, comparison, recommendations, and persistent schedule management. No obvious gaps for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables searching Brown University courses, getting detailed course info, and checking schedule conflicts via natural language, using the university's public course catalog API.
      5
      -
    • F
      license
      A
      quality
      D
      maintenance
      Local-first Rutgers course planning assistant that answers 'what should I take and when?' using a CP-SAT solver, real transcript data, and live SOC data, connected to Claude via MCP.
      13
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables users to query official undergraduate and graduate course schedules, indexes, prerequisites, and exam timetables, including tools for comparing indexes and finding matching schedules. It is read-only, local, and supports filtering by days, times, lesson types, teaching weeks, and schedule clashes.
      7
      1,874 PyPI
      1
      MIT