Skip to main content
Glama
Sign In
piazza-mcp

piazza-mcp

by jadenpxrk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mcp-piazza

CI PyPI Python OpenSSF Scorecard License: MIT

A read-only Model Context Protocol server for Piazza. It works with every MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, Cline, Codex, Gemini CLI, Goose, opencode, JetBrains, LM Studio, Continue, and others.

Ask your assistant about your courses:

  • "What did I miss on Piazza this week?"

  • "Are there unresolved questions about HW3 in CSE 12?"

  • "Did anyone already ask about the midterm room?"

  • "When are the TA office hours?"

  • "What did the instructor change in @142?"

The server only reads data. It cannot post, edit, endorse, or delete.

Quick start

  1. Install uv.

  2. Log in one time. The command opens a login page in your browser:

    uvx mcp-piazza login

    You can also skip this step. If the server has no session, the first tool call opens the same page and shows its link.

  3. Add the server to your client. The server command is uvx with the argument mcp-piazza. For example:

    claude mcp add --scope user --transport stdio piazza -- uvx mcp-piazza   # Claude Code
codex mcp add piazza -- uvx mcp-piazza                                   # Codex CLI

    See docs/clients.md for Claude Desktop, Cursor, VS Code, Windsurf, Zed, Gemini CLI, and other clients.

  4. Ask: "List my Piazza courses."

Related MCP server: Horizon

Tools, prompts and resources

Tool

Purpose

list_courses

List your courses with ID, course number, term, role, active status, and folders.

get_course_info

Get the course page: description, syllabus, office hours, general information, and staff with emails.

get_unread_counts

Count unread posts in each active course.

recent_activity

List posts with new activity since a time (24h, 7d, 2026-10-01), in all active courses or one course.

list_posts

List post summaries. Filters: all, unread, following, unresolved, unanswered, mine, starred. Optional folder and paging.

search_posts

Search posts by keywords in one course or in all active courses.

get_post

Read one full thread: question, instructor answer, student answer, followups, replies, and poll data.

get_posts

Read up to 20 full threads in one call.

get_post_history

Show every version of a post, with a diff between versions.

list_instructor_notes

List notes and polls written by instructors.

get_attachment

Open an image or file from a post. The model can see images.

get_course_stats

Get the data from the course Statistics page.

Every tool accepts a course ID, a course number such as CSE 12 or cse12, or part of the course name.

Prompt

Purpose

catch_up

Read all posts since a time and summarize them, with actions for you.

before_asking

Find out if a question was already asked and answered.

exam_prep

Read all posts about an exam or topic and collect the facts.

Many clients show prompts as slash commands.

Skill

Purpose

piazza-catch-up

The catch_up steps, for agents that use skills.

piazza-exam-prep

The exam_prep steps.

piazza-before-asking

The before_asking steps.

Skills work in Claude Code, Cursor, Codex, opencode, and other agents. They need the server. To install them:

npx skills add jadenpxrk/mcp-piazza

Resource

Content

piazza://courses

Your courses

piazza://courses/{course_id}/posts/{number}

One full thread

See docs/tools.md for parameters and output fields, and docs/workflows.md for examples.

Authentication

Piazza has no public API. This server uses piazza-api, which logs in as the Piazza website does.

Method

How

Use it when

Login page

mcp-piazza login, or the link from the first tool call

Most people. The page offers the three methods below.

Browser session

mcp-piazza login --browser

You are logged in to piazza.com in Chrome, Arc, Brave, Edge, Firefox, Safari, Chromium, Vivaldi, or Opera. This works with school SSO.

Password

mcp-piazza login --password

You want to type your email and password in the terminal.

Session cookie

mcp-piazza login --cookie

You want to paste the session_id cookie from the browser developer tools.

Environment variables

PIAZZA_EMAIL, PIAZZA_PASSWORD

You want automatic login when the session expires.

All methods save only the session cookies to ~/.config/mcp-piazza/cookies.json with file mode 600. They do not save your password. When the session expires, the next tool call opens the login page again. mcp-piazza logout deletes the session.

Configuration

Variable

Default

Purpose

PIAZZA_EMAIL

none

Account email for automatic login.

PIAZZA_PASSWORD

none

Account password for automatic login.

PIAZZA_COOKIE_FILE

~/.config/mcp-piazza/cookies.json

Path of the saved session.

PIAZZA_ANONYMIZE_STUDENTS

false

Replace student names with pseudonyms.

PIAZZA_FENCE_CONTENT

true

Mark post text as untrusted data.

PIAZZA_KEEP_UNREAD

false

Mark unread posts unread again after the server reads them.

PIAZZA_MIN_INTERVAL

0.5

Minimum seconds between Piazza requests.

PIAZZA_CACHE_TTL

60

Seconds to keep feeds and posts in memory. 0 turns off the cache.

See docs/configuration.md for examples and the command line.

Privacy and safety

  • Read-only. The server has no tools that change Piazza data. The only write is the optional PIAZZA_KEEP_UNREAD restore.

  • Prompt-injection fencing. Other course members write the post text. The server puts that text between <<<UNTRUSTED PIAZZA TEXT ...>>> markers, and the server instructions tell the model to treat it as data.

  • Student pseudonyms. When PIAZZA_ANONYMIZE_STUDENTS=true, other students show as Student 3f2a1c. Staff keep their names. Your own posts show as you.

  • Local only. The server runs on your computer. It sends your cookies only to piazza.com.

See docs/privacy.md for the full model and its limits.

Development

uv sync
uv run pytest               # offline tests, no Piazza account needed
uv run ruff check src tests
uv run ruff format src tests
uv run mypy src

See AGENTS.md for the project layout and rules.

Limitations

  • Piazza can change its internal API at any time. If tools fail after a Piazza update, see docs/troubleshooting.md.

  • When the server reads a full post, Piazza marks the post as read and counts a view, as the website does. Set PIAZZA_KEEP_UNREAD=true to mark unread posts unread again.

  • The course page files and links (the Resources tab) are not available. get_course_info shows the names of the resource sections only.

  • Piazza does not document the poll format. get_post returns the poll data as Piazza sends it.

  • Some instructors hide the Statistics page. For those courses, get_course_stats returns an error.

License

MIT. This project is not affiliated with Piazza.

Available Tools

12 tools
get_attachmentGet AttachmentA
Read-onlyIdempotent

Open a file or image that a post links to, such as an [image: ...] link or a piazza.com upload link.

Images come back as images that the model can see. Text files come back as text. Other files, such as PDFs, come back as an embedded file if the client supports it. The maximum size is 10 MB.

Inputs: url (required).

get_course_infoGet Course InfoA
Read-onlyIdempotent

Get the course page: description, syllabus, office hours, general information, dates, and the staff list with names, roles and emails. Use it to find who teaches the course or when office hours are.

Inputs: course (required). Returns: id, url, name, term, +14 more

get_course_statsGet Course StatsB
Read-onlyIdempotent

Get the data from the course Statistics page. Some instructors hide this page from students.

Inputs: course (required). Returns: object

get_postGet PostB
Read-onlyIdempotent

Read one full thread: the question or note, both answers, and followups with replies.

number is the post number that Piazza shows as @123.

Inputs: course (required), number (required). Returns: url, poll, tags, type, +16 more

get_post_historyGet Post HistoryA
Read-onlyIdempotent

Show every version of a post, oldest first, with author and time.

With diff=true, version 1 has the full text and each later version has only a diff from the version before. Use it to see what an instructor changed in an announcement or a question.

Inputs: course (required), number (required), diff. Returns: url, course, number, versions

get_postsGet PostsB
Read-onlyIdempotent

Read up to 20 full threads from one course in one call. A post that cannot be read has an "error" field.

Inputs: course (required), numbers (required). Returns: posts

get_unread_countsGet Unread CountsA
Read-onlyIdempotent

Count the posts with unread content in each course. Sends one request per course.

By default only active courses are counted. Courses with no unread posts are left out.

Inputs: include_inactive. Returns: total, courses

list_coursesList CoursesA
Read-onlyIdempotent

List the user's Piazza courses with ID, course number, term, role, active status, and post folders.

Other tools accept the ID, the course number, or part of the name. Set refresh=true to reload from Piazza.

Inputs: refresh. Returns: result

list_instructor_notesList Instructor NotesB
Read-onlyIdempotent

List notes and polls written by instructors, such as announcements and logistics, most recent first.

Inputs: course (required), limit. Returns: count, posts, query, course, +2 more

list_postsList PostsA
Read-onlyIdempotent

List post summaries for a course, most recent activity first.

filter: "unread" = posts with content the user has not read. "following" = posts the user follows. "unresolved" = unanswered questions and posts with unresolved followups. "unanswered" = questions with no answer. "mine" = the user's own posts that show their name. "starred" = posts the user starred. folder: only posts in this folder, for example "hw1". list_courses shows the folder names. Summaries have a short snippet only. Call get_post or get_posts for full threads.

Inputs: course (required), limit, filter, folder, +1 more. Returns: count, posts, query, course, +2 more

recent_activityRecent ActivityB
Read-onlyIdempotent

List posts with new activity since a time, in all active courses or in one course.

since: a relative age such as 24h, 7d or 2w, or an ISO date such as 2026-10-01. The default is 7d. Use this tool for questions such as "what did I miss this week". Courses without activity are left out.

Inputs: limit, since, course, include_inactive. Returns: query, since, courses

search_postsSearch PostsA
Read-onlyIdempotent

Search posts by keywords, like the Piazza search box, in one course or in all active courses.

Use it before the user asks a new question, to find duplicates. Returns post summaries grouped by course.

Inputs: query (required), limit, course. Returns: query, since, courses

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes (e.g., get_course_stats vs get_course_info vs list_courses), but there is potential overlap between get_post and get_posts, and between list_posts and recent_activity; however, descriptions clarify their differences. The main ambiguity is that get_posts can read multiple threads, which might be confused with get_post or list_posts, but it's minor because of clear guidance.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with verb_noun structure (e.g., get_course_stats, list_courses, get_post_history). No deviations or mixed conventions are present.

    Tool Count5/5

    12 tools is well-scoped for a Piazza client, covering courses, posts, search, activity, and attachments without being excessive or too thin. Each tool appears to earn its place.

    Completeness4/5

    The tool surface covers many key operations: listing courses/posts, searching, reading threads, getting attachments, and instructor notes. However, obvious gaps exist: there is no tool to create or reply to posts, and no way to mark posts as read/unread or star/unstar, which are common Piazza actions. These gaps are minor but could limit agent workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers