MCP Tools Reference: classroommcp.googleapis.com

工具:list_courses

列出用户的课程及其详细信息(班级、教室、科目、年级、说明、学习目标、状态和用户角色)。将此作为主要入口点,用于发现课程并检索其 ID。课程通常具有相同的标题,因此请使用“章节”来区分它们。仅返回 ACTIVE 课程,除非设置了 courseState(例如 ARCHIVED)。

如需将用户链接到 Google 课堂 Web 应用中的课程,请使用 https://classroom.google.com/c/{course_id}(信息流)或 https://classroom.google.com/w/{course_id}/t/all(“课业”页面)。请严格按照返回的 ID 使用,切勿猜测或修改。

以下代码示例展示了如何使用 curl 调用 list_courses MCP 工具。

Curl 请求
curl --location 'https://classroommcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_courses",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

请求列出课程。

ListCoursesRequest

JSON 表示法
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
字段
courseState

enum (State)

可选。按课程状态过滤。默认为 ACTIVE。

createdDateRange

object (DateRange)

可选。按创建日期范围过滤。

timeZone

string

必需。用户的 IANA 时区(例如 "America/Los_Angeles")。此请求中的日期会按该时区进行解读,响应中的日期也会按该时区进行格式化,与用户在 Google 课堂中看到的日期一致。

titleContains

string

可选。按不区分大小写的子字符串过滤标题。

pageSize

integer

可选。控制页面大小。默认值为 10;最大值为 50。

pageToken

string

可选。用于分页的令牌。

DateRange

JSON 表示法
{
  "startDate": string,
  "endDate": string
}
字段
startDate

string

范围的开始日期(包含在范围内,格式:YYYY-MM-DD)。

endDate

string

范围的结束日期(含,格式:YYYY-MM-DD)。

州

课程的状态。

枚举
STATE_UNSPECIFIED 未指定状态。
ACTIVE 活跃状态。
ARCHIVED 已归档状态。
PROVISIONED 预配状态。

输出架构

对列出课程的请求做出的响应。

ListCoursesResponse

JSON 表示法
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
字段
courses[]

object (Course)

课程列表。

nextPageToken

string

下一页令牌。

课程

JSON 表示法
{
  "id": string,
  "title": string,
  "role": enum (Role),
  "creationDate": string,
  "state": enum (State),
  "section": string,
  "room": string,
  "subject": string,
  "gradeLevels": string,
  "description": string,
  "learningGoals": [
    {
      object (LearningGoal)
    }
  ]
}
字段
id

string

标识符。此课程的标识符。

title

string

课程的标题。

role

enum (Role)

用户在此课程中的角色。

creationDate

string

课程的创建日期(格式:YYYY-MM-DD)。如果创建日期未知,则为空。

state

enum (State)

仅限输出。课程的状态。

section

string

可选。课程章节。

room

string

可选。课程的教室。

subject

string

可选。课程主题。

gradeLevels

string

可选。课程的年级。

description

string

可选。课程的说明。

learningGoals[]

object (LearningGoal)

仅限输出。附加到此课程的学习目标。

LearningGoal

JSON 表示法
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
字段
id

string

仅限输出。学习目标的 ID。如需附加标准,请使用 search_course_standards 中的 id(而非 standardCode)。

type

enum (Type)

仅限输出。学习目标的类型。

standardCode

string

仅限输出。标准代码(例如“NY-2.NBT.4”)。仅针对标准进行填充。

title

string

仅限输出。标准的陈述说明,或技能的人类可读标题。

documentTitle

string

仅限输出。课程文档名称。仅针对标准进行填充。

角色

用户在课程中的角色。

枚举
ROLE_UNSPECIFIED 未指定角色。
TEACHER 教师角色。
COTEACHER 助理教师角色。
STUDENT 学生角色。
INVITED_OR_INACTIVE 受邀或非活跃角色。

州

课程的状态。

枚举
STATE_UNSPECIFIED 未指定状态。
ACTIVE 活跃状态。
ARCHIVED 已归档状态。
PROVISIONED 预配状态。

类型

学习目标的类型。

枚举
TYPE_UNSPECIFIED 未指定学习目标类型。
STANDARD 学术课程中的学业标准。
SKILL 代表教育概念或能力的技能。在 Google 课堂中,只有教师可以添加或移除技能。

工具注释

工具注解会发送到 MCP 客户端,用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信,但它们可用于决定何时向用户发送确认提示。

除了标题字符串之外,还定义了以下布尔值提示:

  • readOnlyHint:如果为 true,则该工具不会修改其环境。默认值:false。
  • destructiveHint:如果为 true,则该工具可以执行破坏性操作。如果为 false,则该工具只能执行添加操作。默认值:true。
  • idempotentHint:如果为 true,则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值:false。
  • openWorldHint:如果为 true,则该工具可以与外部实体的“开放世界”进行交互。如果为 false,则该工具只能与内部实体交互。例如,网页搜索工具是开放式的,而记忆工具不是开放式的。

破坏性提示:❌ | 等幂性提示:✅ | 只读提示:✅ | 开放世界提示:❌

授权范围

需要以下 OAuth 范围之一:

  • https://www.googleapis.com/auth/classroom.courses.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly