MCP Tools Reference: gmailmcp.googleapis.com

เครื่องมือ: search_threads

แสดงรายการเธรดอีเมลจากบัญชี Gmail ของผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์

เครื่องมือนี้สามารถกรองเธรดตามสตริงการค้นหาและรองรับการแบ่งหน้า โดยจะแสดงผลรายการชุดข้อความ รวมถึงรหัสและข้อความที่เกี่ยวข้อง ข้อความที่เกี่ยวข้องแต่ละข้อความจะมีรายละเอียด เช่น ตัวอย่างเนื้อความ หัวเรื่อง ผู้ส่ง ผู้รับ ฯลฯ พารามิเตอร์ view จะควบคุมฟิลด์ที่จะแสดงในข้อความที่เกี่ยวข้อง โดยค่าเริ่มต้น (หรือเมื่อใช้ THREAD_VIEW_MINIMAL) จะมีหัวเรื่องและตัวอย่างข้อมูล ใช้ THREAD_VIEW_METADATA_ONLY เพื่อยกเว้นเรื่องและข้อมูลโค้ด โปรดทราบว่าเครื่องมือนี้จะไม่แสดงเนื้อความของข้อความทั้งหมด หากต้องการดึงเนื้อความของข้อความทั้งหมด ให้ใช้เครื่องมือ "get_thread" กับรหัสชุดข้อความ เธรดที่มีเกณฑ์ที่ยกเว้นอาจยังปรากฏในผลการค้นหา ซึ่งเกิดขึ้นเนื่องจาก Gmail ระบุข้อความที่ตรงกันก่อน เช่น หากคุณค้นหา -is:starred Gmail จะค้นหาชุดการสนทนาทั้งหมดได้หากมีข้อความที่ไม่ได้ติดดาวไว้อย่างน้อย 1 รายการ แม้ว่าอีเมลอื่นๆ ในการสนทนาเดียวกันนั้นจะติดดาวอยู่ก็ตาม

ตัวอย่างต่อไปนี้แสดงวิธีใช้ curl เพื่อเรียกใช้เครื่องมือ search_threads MCP

คำขอ Curl 
curl --location 'https://gmailmcp.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": "search_threads",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

สคีมาอินพุต

ข้อความคำขอสำหรับ RPC ของ SearchThreads

SearchThreadsRequest

การแสดง JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
ช่อง

ฟิลด์ Union _page_size

_page_size ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
pageSize

integer

ไม่บังคับ จำนวนสูงสุดของเธรดที่จะแสดง หากไม่ระบุ ระบบจะกำหนดค่าเริ่มต้นไว้ที่ 20 ค่าสูงสุดที่อนุญาตคือ 50

ฟิลด์ Union _page_token

_page_token ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
pageToken

string

ไม่บังคับ โทเค็นหน้าเว็บเพื่อดึงข้อมูลหน้าผลลัพธ์ที่เฉพาะเจาะจงในรายการ เว้นว่างไว้เพื่อดึงข้อมูลหน้าแรก โดยส่วนใหญ่จะใช้สำหรับการแบ่งหน้าเพื่อดึงผลลัพธ์ต่อจากที่SearchThreadsการเรียกก่อนหน้าหยุดไว้ โดยเฉพาะอย่างยิ่งเมื่อจำนวนเธรดที่ตรงกับการค้นหาเกินขีดจำกัด page_size

ฟิลด์ Union _query

_query ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
query

string

ไม่บังคับ สตริงการค้นหาเพื่อกรองชุดข้อความ ต้องแปลงคำค้นหาที่เป็นภาษาธรรมชาติเป็นคำค้นหาไวยากรณ์ Gmail ล่วงหน้าเพื่อใช้เครื่องมือนี้ หากไม่ระบุ ระบบจะแสดงรายการเธรดทั้งหมด (ยกเว้นจดหมายขยะและถังขยะโดยค่าเริ่มต้น)

โอเปอเรเตอร์ที่รองรับตามหมวดหมู่

ผู้ส่งและผู้รับ

  • from:<email> — ส่งจากบุคคลที่เฉพาะเจาะจง
  • to:<email> — ส่งถึงบุคคลที่เฉพาะเจาะจง
  • cc:<email> — บุคคลที่ระบุในสำเนา
  • bcc:<email> — บุคคลที่เฉพาะเจาะจงในสำเนาลับ
  • deliveredto:<email> — นำส่งไปยังที่อยู่ที่เฉพาะเจาะจง
  • list:<email> — จากรายชื่ออีเมลที่เฉพาะเจาะจง

เวลาและวันที่:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD — ได้รับหลังจากวันที่
  • before:YYYY/MM/DD / older:YYYY/MM/DD — ได้รับก่อนวันที่
  • older_than:<duration> — เก่ากว่าระยะเวลา (เช่น 1y, 2d)
  • newer_than:<duration> — ใหม่กว่าระยะเวลา

เนื้อหา:

  • subject:<words> — คำในบรรทัดเรื่อง
  • has:<type> — มีประเภทเนื้อหาที่เฉพาะเจาะจง (ไฟล์แนบ ไดรฟ์ YouTube เอกสาร)
  • filename:<name> — ไฟล์แนบที่มีชื่อหรือประเภทที่เฉพาะเจาะจง
  • "<word/phrase>" — ค้นหาคำหรือวลีที่ตรงกัน (เช่น "holiday", "holiday vacation")
  • +<word> — ตรงกับคำทุกประการ (เช่น +holiday, +unicorn)
  • rfc822msgid:<id> - ส่วนหัวของรหัสข้อความที่เฉพาะเจาะจง
  • AROUND <distance> — ค้นหาคำที่อยู่ใกล้กัน (เช่น holiday AROUND 10 vacation)

ป้ายกำกับและหมวดหมู่

  • label:<name> — ภายใต้ป้ายกำกับที่เฉพาะเจาะจง เครื่องมือนี้ยอมรับรหัสค่ายเพลง ไม่ใช่ชื่อที่แสดง ใช้เครื่องมือ list_labels เพื่อรับรหัส
  • category:<name> — ในหมวดหมู่ (หลัก โซเชียล โปรโมชัน อัปเดต ฟอรัม การจอง การซื้อ)
  • in:<label> — ค้นหาในป้ายกำกับที่เฉพาะเจาะจง (ที่เก็บ ถังขยะ กล่องจดหมายที่ส่ง กล่องจดหมาย) เช่น in:trash, in:inbox ระบบจะรวมข้อความที่เก็บไว้และข้อความที่ส่งโดยค่าเริ่มต้น ให้ใช้ -in:archive และ -in:sent เพื่อยกเว้นข้อความดังกล่าว เครื่องมือจะยกเว้นฉบับร่างโดยชัดแจ้งโดยค่าเริ่มต้น ใช้ in:inbox เพื่อจำกัดการค้นหาเฉพาะในกล่องจดหมาย
  • has:userlabels - มีป้ายกำกับของผู้ใช้
  • has:nouserlabels — ไม่มีป้ายกำกับผู้ใช้
  • has:*-star — สีดาวที่เฉพาะเจาะจง (หากเปิดใช้ เช่น has:yellow-star)
  • in:draft — ค้นหาในฉบับร่าง -in:draft หมายถึงไม่รวมฉบับร่างจากผลการค้นหา
  • in:sent — ค้นหาในข้อความที่ส่ง
  • in:anywhere — ค้นหาในโฟลเดอร์ทั้งหมด (รวมถึงจดหมายขยะและถังขยะ)

สถานะ:

  • is:<status> — ค้นหาตามสถานะ (สำคัญ ติดดาว ยังไม่อ่าน อ่านแล้ว ปิดเสียง)

ขนาด:

  • size:<bytes> — ขนาดที่เฉพาะเจาะจงในหน่วยไบต์
  • larger:<size> / smaller:<size> — ใหญ่กว่าหรือเล็กกว่าขนาด (เช่น 10M สำหรับ 10 MB)

ตรรกะและการจัดกลุ่ม:

  • AND — ตรงตามเกณฑ์ทั้งหมด (ลักษณะการทำงานเริ่มต้น)
  • OR หรือ { } — ตรงกับเกณฑ์อย่างน้อย 1 รายการ (เช่น from:amy OR from:david, {from:amy from:david})
  • - (ลบ) - ยกเว้นเกณฑ์ (เช่น -movie)
  • ( ) — จัดกลุ่มข้อความค้นหาหลายรายการ (เช่น subject:(dinner film))

ตัวอย่าง

  • subject:OneMCP Update
  • from:user@example.com
  • to:user2@example.com AND newer_than:7d
  • project proposal has:attachment
  • is:unread -in:draft

ฟิลด์ Union _include_trash

_include_trash ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
includeTrash

boolean

ไม่บังคับ รวมเธรดจากถังขยะไว้ในผลการค้นหา ค่าเริ่มต้นคือ false

ฟิลด์ Union _view

_view ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
view

enum (ThreadView)

ไม่บังคับ ควบคุมช่องที่ป้อนข้อมูลสำหรับชุดข้อความในรายการชุดข้อความ ค่าเริ่มต้นคือ THREAD_VIEW_MINIMAL THREAD_VIEW_MINIMAL จะแสดงผล id, snippet, subject, from, to, cc, date, labelIds THREAD_VIEW_METADATA_ONLY จะแสดงผล id, from, to, cc, date, labelIds

ThreadView

Enum เพื่อควบคุมฟิลด์ที่สร้างขึ้นสำหรับชุดข้อความในการตอบกลับ ListThreads และ SearchThreads

Enum
THREAD_VIEW_UNSPECIFIED แมปกับ THREAD_VIEW_MINIMAL เพื่อความเข้ากันได้แบบย้อนหลัง
THREAD_VIEW_METADATA_ONLY แสดงผลรหัส จาก ถึง สำเนา วันที่ และ labelIds
THREAD_VIEW_MINIMAL แสดงผล id, snippet, subject, from, to, cc, date, labelIds

สคีมาเอาต์พุต

ข้อความตอบกลับสำหรับ RPC ของ SearchThreads

SearchThreadsResponse

การแสดง JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
ช่อง
threads[]

object (Thread)

รายการข้อมูลสรุปของชุดข้อความ
nextPageToken

string

โทเค็นที่ใช้ในการเรียกครั้งถัดไปเพื่อดึงข้อมูลหน้าถัดไปของเธรดได้ แสดงเฉพาะในกรณีที่มีผลลัพธ์เพิ่มเติม หากจำนวนชุดข้อความที่ตรงกับการค้นหาเกินขีดจำกัด page_size การตอบกลับจะมี next_page_token หากต้องการดึงข้อมูลผลลัพธ์ในหน้าถัดไป ให้ส่งโทเค็นนี้ในช่อง page_token ของ SearchThreadsRequest รายการถัดไป
resultCountEstimate

string (int64 format)

จำนวนผลลัพธ์โดยประมาณสําหรับการค้นหานี้ ควรถือว่าเป็นขอบเขตล่าง เช่น หากเป็น 500 ระบบจะรายงานจำนวนต่อผู้ใช้เป็น "500 ขึ้นไป"

ชุดข้อความ

การแสดง JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
ช่อง
id

string

ตัวระบุที่ไม่ซ้ำกันของเธรด
messages[]

object (Message)

รายการข้อความในชุดข้อความที่จัดเรียงตามลำดับเวลา

ข้อความ

การแสดง JSON 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    string
  ]
}
ช่อง
id

string

ตัวระบุที่ไม่ซ้ำกันของข้อความ
snippet

string

ข้อมูลโค้ดของเนื้อความ
subject

string

เรื่องของข้อความที่ดึงมาจากส่วนหัว
sender

string

อีเมลของผู้ส่ง
toRecipients[]

string

ไปยังอีเมลของผู้รับ
ccRecipients[]

string

อีเมลของผู้รับในสำเนา
date

string

วันที่ของข้อความในรูปแบบ ISO 8601 (YYYY-MM-DD)
plaintextBody

string

เนื้อหาข้อความแบบเต็ม จะแสดงก็ต่อเมื่อ MessageFormat เป็น FULL_CONTENT เท่านั้น
attachmentIds[]

string

เอาต์พุตเท่านั้น รหัสไฟล์แนบ จะแสดงก็ต่อเมื่อ MessageFormat เป็น FULL_CONTENT เท่านั้น
htmlBody

string

เนื้อหา HTML ของอีเมล จะแสดงก็ต่อเมื่อ MessageFormat เป็น FULL_CONTENT
attachments[]

object (AttachmentMetadata)

เอาต์พุตเท่านั้น ไฟล์แนบจะแสดงก็ต่อเมื่อ MessageFormat เป็น FULL_CONTENT เท่านั้น
labelIds[]

string

รหัสของป้ายกำกับที่แนบกับข้อความ รวมรหัสของป้ายกำกับที่ผู้ใช้สร้างขึ้นและป้ายกำกับของระบบมาตรฐานที่จำกัดไว้สำหรับ INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT

AttachmentMetadata

การแสดง JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
ช่อง
id

string

เอาต์พุตเท่านั้น รหัสของไฟล์แนบ
mimeType

string

ประเภท MIME ของไฟล์แนบ
filename

string

ชื่อไฟล์ของไฟล์แนบ

คำอธิบายประกอบเครื่องมือ

คำแนะนำที่ทำลายล้าง: ❌ | คำแนะนำที่ทำซ้ำได้: ✅ | คำแนะนำแบบอ่านอย่างเดียว: ✅ | คำแนะนำแบบโลกเปิด: ❌

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth อย่างใดอย่างหนึ่งต่อไปนี้

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly