classroom MCP

谷歌课堂MCP服务器

一个MCP（模型上下文协议）服务器，将克劳德连接到你的谷歌课堂帐户，让你通过自然语言查询你的课程、作业、成绩等。

可用工具

所有访问权限均为 只读。服务器无法在您的Google课堂帐户中创建、修改或删除任何内容。

______________________________________________________________________

设置

先决条件

• Node.js v16或更高版本
• 启用课堂API的谷歌云项目

步骤1--克隆并安装

git clone https://github.com/SalShah20/classroom_mcp.git
cd classroom_mcp
npm install
npm run build

步骤2-创建一个谷歌云项目并启用课堂API

1. 首选 console.cloud.google.com
2. 创建新项目（或选择现有项目）
3. 在左侧菜单中，转到 API和服务>库
4. 搜索 谷歌课堂API 然后单击 启用

步骤3——创建OAuth 2.0凭据

1. 首选 API和服务>凭据
2. 点击 创建凭据>OAuth 2.0客户端ID
3. 如果系统提示，请先配置OAuth同意屏幕：

- 将用户类型设置为 外部 - 填写应用程序名称（任何东西都可以，例如“课堂MCP”） - 将您的Google帐户电子邮件添加为测试用户

1. 返回凭据页面，选择 桌面应用 作为应用程序类型
2. 点击 创建那么 下载JSON
3. 将下载的文件重命名为 credentials.json 并将其放置在项目根文件夹中

步骤4——身份验证

npm run setup-auth

这将：

1. 阅读你的 credentials.json
2. 打印URL-- 复制它并在浏览器中打开它
3. 使用您的Google帐户登录并单击 允许
4. 谷歌将向您显示授权码-- 复制它
5. 将代码粘贴回终端，然后按Enter键

关于成功，a .env 文件是在项目根目录中创建的，其中包含您的凭据。在下一步中，您将需要这些值。

未收到刷新令牌？ 如果您之前已授权该应用程序，则可能会出现这种情况。首选 myaccount.google.com/permissions，删除应用程序的访问权限，然后运行 npm run setup-auth 再一次。

步骤5--将服务器添加到Claude Desktop

打开您的Claude Desktop配置文件：

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下条目（更新路径和凭据值）：

{
  "mcpServers": {
    "google-classroom": {
      "command": "node",
      "args": ["C:/path/to/classroom_mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

要找到你的价值观，请打开 .env 在步骤4中创建的文件——它包含所有三个具有匹配名称的值。

重新启动克劳德桌面 保存配置后。

______________________________________________________________________

验证它是否有效

重新启动Claude Desktop后，尝试询问Claude：

• “列出我的所有谷歌课堂课程”
• “这周我有什么作业要做？”
• “我有没有遗漏的作业？”
• “给我看我历史课的成绩”
• “我的生物学总成绩百分比是多少？”
• “第5章作业附有哪些材料？”

______________________________________________________________________

Google API范围

服务器请求以下只读作用域：

没有请求写入范围。服务器无法修改您的Google课堂帐户中的任何数据。

______________________________________________________________________

在本地运行（不带Claude Desktop）

# Build
npm run build

# Run the server directly (reads credentials from .env automatically)
npm start

______________________________________________________________________

项目结构

classroom_mcp/
├── src/
│   ├── index.ts          # Main server — all tools are defined here
│   └── setup-auth.ts     # Interactive authentication setup
├── dist/                 # Compiled output (generated by npm run build)
├── credentials.json      # Your Google OAuth credentials (not committed to git)
├── .env                  # Your tokens after running setup-auth (not committed to git)
├── tokens.json           # Legacy token file for backward compatibility (not committed to git)
├── package.json
├── tsconfig.json
└── README.md

______________________________________________________________________

API 参考

课程

• list_courses(courseStates?, teacherId?, studentId?) --列出课程，可选择按状态过滤（ACTIVE、ARCHIVED等）
• get_course(courseId) --获取一门课程的完整详细信息

作业

• get_assignments(courseId) --列出课程中所有已发布的作业，包括标题、截止日期、最高分数和类型
• list_coursework(courseId, courseWorkStates?) --列出课程中的作业，可选择按状态筛选（已发布、草稿、已删除）
• get_coursework(courseId, courseWorkId) --获取特定任务的完整详细信息
• get_assignment_materials(courseId, courseWorkId) --获取所有附加材料（驱动器文件、链接、YouTube视频、谷歌表单）
• get_upcoming_assignments(days?) --下一期作业到期 days 所有活动课程的天数，按截止日期排序。默认为7天
• get_missing_assignments() --所有活动课程中未提交的逾期作业

成绩和提交

• get_grades() --您在所有活动课程中的每项作业的成绩，包括 assignedGrade, maxPoints, state，以及 dueDate
• calculate_grade(courseId) --一门课程的总成绩百分比加上每项作业的细分
• list_submissions(courseId, courseWorkId) --您自己为特定任务提交的详细信息

公告

• list_announcements(courseId, announcementStates?) --列表公告

______________________________________________________________________

故障排除

credentials.json not found 确保文件位于项目根目录中（与 package.json)，不在子文件夹中。

No refresh token received 在以下位置撤销应用程序的现有访问权限 myaccount.google.com/permissions，然后重新运行 npm run setup-auth.

Google Classroom API not initialized 服务器找不到凭据。确保 env Claude Desktop配置中的块具有所有三个值(GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN).

服务器未出现在Claude Desktop中

• 检查中的文件路径 args 指向 dist/index.js 并使用正确的绝对路径
• 确保你跑了 npm run build 所以 dist/index.js 存在
• 编辑配置后完全重新启动Claude Desktop

构建错误

npm run clean
npm install
npm run build

______________________________________________________________________

安全说明

• 所有作用域都是只读的——服务器无法修改您的课堂数据
• 使用存储的刷新令牌自动刷新访问令牌
• 刷新令牌存储在您的本地计算机上，从不存储在远程服务器上