MCP Tools Reference: gmailmcp.googleapis.com

כלי: search_threads

מחזירה רשימה של שרשורי אימייל מחשבון Gmail של המשתמש המאומת.

הכלי הזה יכול לסנן שרשורים על סמך מחרוזת שאילתה, והוא תומך בחלוקה לעמודים. הפונקציה מחזירה רשימה של שרשורים, כולל המזהים שלהם וההודעות שקשורות אליהם. כל הודעה קשורה מכילה פרטים כמו קטע מגוף ההודעה, הנושא, השולח, הנמענים וכו'. הפרמטר view קובע אילו שדות יאוכלסו בהודעות הקשורות. כברירת מחדל (או עם THREAD_VIEW_MINIMAL), הוא כולל את הנושא ואת התקציר. כדי להחריג את הנושא ואת התקציר, משתמשים ב-THREAD_VIEW_METADATA_ONLY. שימו לב: הכלי הזה לא מחזיר את גוף ההודעה המלא. אם אתם צריכים את גוף ההודעה המלא, אתם צריכים להשתמש בכלי get_thread עם מזהה השרשור. יכול להיות שעדיין יופיעו בתוצאות שרשורים עם קריטריונים מוחרגים. הסיבה לכך היא ש-Gmail מזהה קודם הודעות תואמות. לדוגמה, אם מחפשים ‎-is:starred, ‏ Gmail ימצא שרשור שלם אם הוא מכיל לפחות הודעה אחת שלא סומנה בכוכב, גם אם הודעות אחרות באותה שיחה סומנו בכוכב.

בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להפעיל את כלי ה-MCP‏ search_threads.

בקשת 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)
}
שדות

שדה איחוד _page_size.

הערך _page_size יכול להיות רק אחד מהבאים:
pageSize

integer

אופציונלי. מספר השרשורים המקסימלי שיוחזרו. אם לא מציינים ערך, ברירת המחדל היא 20. הערך המקסימלי המותר הוא 50.

שדה איחוד _page_token.

הערך _page_token יכול להיות רק אחד מהבאים:
pageToken

string

אופציונלי. אסימון דף לאחזור דף ספציפי של תוצאות ברשימה. אם משאירים את השדה ריק, המערכת מאחזרת את הדף הראשון. הפרמטר הזה משמש בעיקר להחלפה בין דפים כדי להמשיך לאחזר תוצאות מהמקום שבו הסתיימה הקריאה הקודמת ל-SearchThreads, במיוחד כשמספר השרשורים שתואמים לשאילתה חורג מהמגבלה של page_size.

שדה איחוד _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> — מכיל סוגי תוכן ספציפיים (קובץ מצורף, Drive, ‏ 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 ל-10MB).

לוגיקה וקיבוץ:

  • AND – התאמה לכל הקריטריונים (התנהגות ברירת המחדל).
  • ‫OR או { } – התאמה לאחד או יותר מהקריטריונים (לדוגמה, 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

שדה איחוד _include_trash.

הערך _include_trash יכול להיות רק אחד מהבאים:
includeTrash

boolean

אופציונלי. הכללת שרשורים מתיקיית האשפה בתוצאות. ברירת המחדל היא False.

שדה איחוד _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 מחזירה את הערכים id, ‏ from, ‏ to, ‏ cc, ‏ date, ‏ labelIds.
THREAD_VIEW_MINIMAL מחזירה את המזהה, התקציר, הנושא, השולח, הנמען, העותק, התאריך ומזהי התוויות.

סכימת הפלט

הודעת התגובה של 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