MCP Tools Reference: classroommcp.googleapis.com

工具:list_courses

列出使用者的課程和詳細資料 (章節、教室、科目、年級、說明、學習目標、狀態和使用者角色)。請將此做為主要進入點,探索課程並擷取其 ID。課程通常會共用同一個名稱,因此請使用「節」來區分。除非設定 courseState (例如 ARCHIVED),否則只會傳回 ACTIVE 課程。

如要將使用者連結至 Classroom 網頁應用程式中的課程,請使用 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")。這項要求中的日期會以此時區解讀,回應中的日期也會以此時區格式化,與使用者在 Classroom 中看到的內容一致。

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

ID。課程 ID。

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 代表教育概念或能力的技能。只有老師可以在 Classroom 中新增或移除技能。

工具註解

工具註解會傳送至 MCP 用戶端,說明特定工具的基本風險。大多數用戶端會將這些提示視為不受信任,但可用於決定何時向使用者傳送確認提示。

除了標題字串外,下列布林值提示的定義如下:

  • readOnlyHint:如果為 true,工具不會修改環境。預設值:false。
  • destructiveHint:如果為 true,工具可以執行破壞性動作。如果為 false,則工具只能執行附加動作。預設值:true。
  • idempotentHint:如果設為 true,則使用相同引數重複呼叫工具,不會對環境造成額外影響。預設值:false。
  • openWorldHint:如果設為 true,工具就能與外部實體的「開放世界」互動。如果設為 false,工具只能與內部實體互動。舉例來說,網頁搜尋工具屬於開放世界,而記憶工具則不屬於開放世界。

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

授權範圍

需要下列其中一種 OAuth 範圍:

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