Google Classroom自动化服务器

谷歌课堂MCP服务器

A. 模型上下文协议 （MCP）服务器，为AI代理提供对Google Classroom的完全编程访问。专为教育工作者实现复杂、多步骤的自动化工作流程而构建：从批量作业创建和排班管理到提交收集、评分和Drive文件交付。

为什么存在

人工智能代理需要结构化、可靠地访问教育平台，才能在教学工作流程中真正发挥作用。该服务器诞生于将人工智能助手集成到实际课堂管理中的需要——自动化重复性任务，编排多步骤流程（创建主题→ 分配工作→ 收集意见→ 成绩），让基于LLM的工具作为教师的得力助手。

特性

• 46个完全实施的工具 --课程、主题、作业、材料、公告、提交、评分、名册、监护人、量规和驱动器文件管理
• Google Drive集成 --将文件上传到Drive并将其附加到作业中；下载学生提交的PDF文件
• 默认情况下压缩响应 --列表操作只返回基本字段，以保持在MCP令牌限制范围内；通过 fullData: true 对于完整对象
• OAuth2身份验证 具有持久令牌存储和自动刷新功能
• 环境变量覆盖 为了 credentials.json 和 token.json 路径

安装

先决条件

• Node.js 18+
• 具有Google课堂访问权限的Google帐户（教师角色）
• 启用课堂API的谷歌云项目

步骤1--克隆和构建

git clone https://github.com/adriasantacreu/google-classroom-mcp.git
cd google-classroom-mcp
npm install
npm run build

步骤2——创建Google OAuth凭据

1. 首选 console.cloud.google.com
2. 启用课堂API： API和服务>库>Google Classroom API>启用
3. 首选 API和服务>凭据>创建凭据>OAuth客户端ID
4. 应用程序类型： 桌面应用程序
5. 下载JSON并将其另存为 credentials.json 在项目根中

步骤3——身份验证

node auth.js

在浏览器中打开打印的URL，授权应用程序，粘贴代码。A. token.json 文件在本地创建和存储。

配置您的MCP客户端

选择您的客户端并添加服务器配置。替换 /absolute/path/to/google-classroom-mcp 使用系统上的实际路径。

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "google-classroom": {
      "command": "node",
      "args": ["/absolute/path/to/google-classroom-mcp/dist/index.js"]
    }
  }
}

光标

编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （每个项目）：

{
  "mcpServers": {
    "google-classroom": {
      "command": "node",
      "args": ["/absolute/path/to/google-classroom-mcp/dist/index.js"]
    }
  }
}

VS代码（使用GitHub Copilot）

编辑您的用户 settings.json 或 .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "google-classroom": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/google-classroom-mcp/dist/index.js"]
      }
    }
  }
}

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "google-classroom": {
      "command": "node",
      "args": ["/absolute/path/to/google-classroom-mcp/dist/index.js"]
    }
  }
}

自定义路径（可选）

如果你 credentials.json 或 token.json 不在项目根目录中，请使用环境变量：

{
  "mcpServers": {
    "google-classroom": {
      "command": "node",
      "args": ["/absolute/path/to/google-classroom-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}

编辑配置后重新启动MCP客户端。

OAuth范围

服务器在以下期间请求以下作用域 node auth.js:

工具参考

课程

话题

作业

附件格式 （为 classroom_create_assignment):

"attachments": [
  { "type": "driveFile", "idOrUrl": "<drive-file-id>" },
  { "type": "link",      "idOrUrl": "https://example.com" },
  { "type": "youtubeVideo", "idOrUrl": "<video-id>" },
  { "type": "form",     "idOrUrl": "https://forms.gle/..." }
]

材料

公告

提交

学生名册

名册----教师

守护者

评分标准

用户档案

驱动器和文件附件

已知的API限制

• 课程删除 要求课程 ARCHIVED 首先，该工具会自动处理此问题
• 材料不可编辑 创建后-课堂API不提供材料的PATCH端点； classroom_patch_material 已声明，但对于大多数字段将被API拒绝
• 作业 workType （任务、简短回答问题、多选问题）创建后无法更改
• 作业 state 只能移动到 PUBLISHED -API不支持还原为DRAFT
• 作业附件 创建后无法修改-这是API限制
• drive.file 范围 仅授予对此应用程序创建的文件的访问权限。这 drive.readonly 下载学生上传的提交文件需要范围（默认包含）
• 监护人管理 要求Google Workspace管理员已为域启用监护人功能
• classroom_add_student 发送注册 邀请 --学生必须接受它；它不直接注册
• 修改web创建的内容 — ProjectPermissionDenied 当尝试修补或移动通过课堂网络界面或其他应用程序创建的课程作业时，会返回。API仅允许修改由同一OAuth项目创建的项(associatedWithDeveloper: true).这是Google API的限制，而不是范围问题
• API评价准则 需要 谷歌教育工作区Plus 或 教学和学习升级 许可证。教育基础科目（免费级别）将获得 UserIneligibleToModifyRubrics。参见 谷歌的评分标准限制

故障排除

Authentication token not found. Run auth flow first. 跑 node auth.js 并完成OAuth流程。A. token.json 启动服务器之前，文件必须存在。

Token expired or invalid 删除 token.json 然后跑 node auth.js 再次进行重新认证。

Some requested scopes were invalid 您的令牌是使用过时的作用域列表生成的。删除 token.json 并重新运行 node auth.js.

ProjectPermissionDenied 评分时 经过身份验证的帐户无权在该课程中评分。确认您是课程所有者或合作教师。

UserInIllegalDomain 添加学生时 受邀电子邮件属于您的Google Workspace策略不允许的域。这是一个域级限制，而不是API错误。

列出截断或缺失的字段的响应 默认情况下，列表工具返回紧凑字段以保持在MCP令牌限制范围内。通过 fullData: true 以获得完整的API响应。

客户端中未加载MCP服务器

• 验证配置中的路径指向 dist/index.js，不 src/index.ts
• 确保你跑了 npm run build 任何源更改后
• 配置更改后重新启动MCP客户端

运行测试

测试针对真实的谷歌课堂课程运行，并将创建和删除实时数据。

# Set your test course ID
export TEST_COURSE_ID=your_course_id_here

# Functional tests — one tool at a time, with cleanup
node tests/test-basic.js

# Integration tests — cross-tool workflows and data consistency
node tests/test-integration.js

项目结构

google-classroom-mcp/
├── src/
│   └── index.ts              # MCP server — all 46 tools (TypeScript source)
├── dist/
│   └── index.js              # Compiled output — point your MCP client here
├── tests/
│   ├── test-basic.js         # Functional tests for each tool individually
│   └── test-integration.js   # Cross-tool workflow and consistency tests
├── auth.js                   # OAuth2 token generator
├── smithery.yaml             # Smithery marketplace config
├── credentials.json          # Your OAuth credentials (git-ignored)
├── token.json                # Generated auth token (git-ignored)
└── package.json

贡献

欢迎问题和拉取请求。添加新工具时：

1. 在中声明工具 getTools() 与完整 inputSchema
2. 添加匹配项 case 在 handleToolCall()
3. 在中添加测试 tests/test-basic.js

遵循现有的模式进行紧凑/完整数据响应和错误处理。

许可证

麻省理工学院