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.

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