mcp-piazza

mcp-piazza

一个只读的 Model Context Protocol 服务，用于访问 Piazza。 它适用于所有 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Zed、Cline、Codex、Gemini CLI、Goose、opencode、JetBrains、LM Studio、Continue 等。

向助手询问课程相关问题：

• “这周我错过了 Piazza 上的哪些内容？”
• “CSE 12 中是否有关于 HW3 尚未解决的问题？”
• “有人已经问过期中考试教室的问题了吗？”
• “TA 的办公时间是什么时候？”
• “讲师在 @142 中做了哪些更改？”

该服务只读取数据。它无法发布、编辑、认可或删除内容。

快速开始

1. 安装 uv。

2. 登录一次。该命令会在浏览器中打开登录页面：

   uvx mcp-piazza login
   

   你也可以跳过此步骤。如果服务没有会话，首次调用工具时会打开同一个页面并显示其链接。

3. 将服务添加到客户端。服务命令为 uvx，参数为 mcp-piazza。例如：

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

   Claude Desktop、Cursor、VS Code、Windsurf、Zed、Gemini CLI 和其他客户端的配置方法，请参阅 docs/clients.md。

4. 询问：“列出我的 Piazza 课程。”

工具、提示词和资源

工具	用途
list_courses	列出你的课程，包括 ID、课程编号、学期、角色、活跃状态和文件夹。
get_course_info	获取课程页面信息：课程描述、教学大纲、办公时间、常规信息和包含电子邮件地址的教职员工名单。
get_unread_counts	统计每门活跃课程中的未读帖子数。
recent_activity	列出自某个时间点（24h、7d、2026-10-01）以来有新动态的帖子，可查询所有活跃课程或某一门课程。
list_posts	列出帖子摘要。筛选条件：all、unread、following、unresolved、unanswered、mine、starred。可选文件夹和分页。
search_posts	按关键词搜索某门课程或所有活跃课程中的帖子。
get_post	阅读一条完整帖子串：问题、教师回答、学生回答、后续跟帖、回复和投票数据。
get_posts	一次调用最多阅读 20 条完整帖子串。
get_post_history	显示帖子的所有版本，并提供版本间的差异对比。
list_instructor_notes	列出教师撰写的笔记和投票。
get_attachment	打开帖子中的图片或文件。模型可以查看图片。
get_course_stats	获取课程 Statistics 页面中的数据。

每个工具都接受课程 ID、课程编号（例如 CSE 12 或 cse12），或课程名称的一部分。

提示词	用途
catch_up	阅读某个时间点以来的所有帖子并进行总结，同时列出你可以采取的操作。
before_asking	查找某个问题是否已有人提出并得到回答。
exam_prep	阅读关于某场考试或某个主题的所有帖子，并整理相关信息。

许多客户端会将提示词显示为斜杠命令。

技能	用途
piazza-catch-up	为使用技能的 Agent 提供 catch_up 步骤。
piazza-exam-prep	提供 exam_prep 步骤。
piazza-before-asking	提供 before_asking 步骤。

Claude Code、Cursor、Codex、opencode 和其他 Agent 均可使用这些技能。使用这些技能需要服务端。安装方法：

npx skills add jadenpxrk/mcp-piazza

资源	内容
piazza://courses	你的课程
piazza://courses/{course_id}/posts/{number}	一条完整帖子串

参数和输出字段请参阅 docs/tools.md，示例请参阅 docs/workflows.md。

身份验证

Piazza 没有公共 API。 此服务使用 piazza-api，登录方式与 Piazza 网站相同。

方式	操作方法	适用情况
登录页面	mcp-piazza login，或点击首次工具调用返回的链接	适合大多数人。该页面提供以下三种方式。
浏览器会话	mcp-piazza login --browser	你已在 Chrome、Arc、Brave、Edge、Firefox、Safari、Chromium、Vivaldi 或 Opera 中登录 piazza.com。此方式支持学校 SSO。
密码	mcp-piazza login --password	你想在终端中输入电子邮件地址和密码。
会话 Cookie	mcp-piazza login --cookie	你想从浏览器开发者工具中复制并粘贴 session_id Cookie。
环境变量	PIAZZA_EMAIL、PIAZZA_PASSWORD	你想在会话过期时自动登录。

所有方式都只会将会话 Cookie 保存到 ~/.config/mcp-piazza/cookies.json，文件权限为 600。它们不会保存你的密码。 会话过期后，下次调用工具时会再次打开登录页面。mcp-piazza logout 会删除会话。

配置

变量	默认值	用途
PIAZZA_EMAIL	none	用于自动登录的账户邮箱。
PIAZZA_PASSWORD	none	用于自动登录的账户密码。
PIAZZA_COOKIE_FILE	~/.config/mcp-piazza/cookies.json	已保存会话的路径。
PIAZZA_ANONYMIZE_STUDENTS	false	将学生姓名替换为化名。
PIAZZA_FENCE_CONTENT	true	将帖子文本标记为不可信数据。
PIAZZA_KEEP_UNREAD	false	服务读取未读帖子后，再次将其标记为未读。
PIAZZA_MIN_INTERVAL	0.5	Piazza 请求之间的最短间隔秒数。
PIAZZA_CACHE_TTL	60	在内存中保留动态消息和帖子的秒数。0 可关闭缓存。

示例和命令行用法请参阅 docs/configuration.md。

隐私与安全

• 只读。 服务没有任何可更改 Piazza 数据的工具。唯一的写入操作是可选的 PIAZZA_KEEP_UNREAD 恢复操作。
• 提示词注入隔离。 其他课程成员编写帖子文本。服务会将该文本放在 <<<UNTRUSTED PIAZZA TEXT ...>>> 标记之间，并在服务指令中告知模型将其视为数据。
• 学生化名。 当 PIAZZA_ANONYMIZE_STUDENTS=true 时，其他学生会显示为 Student 3f2a1c。教职员工仍显示其姓名。你自己的帖子会显示为 you。
• 仅限本地。 服务在你的电脑上运行。它只会将你的 Cookie 发送到 piazza.com。

有关完整模型及其限制，请参阅 docs/privacy.md。

开发

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

有关项目结构和规则，请参阅 AGENTS.md。

限制

• Piazza 可能随时更改其内部 API。如果 Piazza 更新后工具无法使用，请参阅 docs/troubleshooting.md。
• 服务读取完整帖子时，Piazza 会像网站一样将帖子标记为已读并计为一次浏览。设置 PIAZZA_KEEP_UNREAD=true 可再次将未读帖子标记为未读。
• 课程页面文件和链接（“资源”选项卡）不可用。get_course_info 仅显示资源分区的名称。
• Piazza 没有记录投票的格式。get_post 会按 Piazza 发送的形式返回投票数据。
• 有些教师会隐藏“统计信息”页面。对于这些课程，get_course_stats 会返回错误。

许可证

MIT。本项目与 Piazza 无关。