MCP Tools Reference: gmailmcp.googleapis.com

도구: search_threads

인증된 사용자의 Gmail 계정에서 이메일 대화목록을 나열합니다.

이 도구는 쿼리 문자열을 기반으로 대화목록을 필터링할 수 있으며 페이지로 나누기를 지원합니다. ID와 관련 메시지를 포함한 대화목록 목록을 반환합니다. 각 관련 메시지에는 메일 본문 미리보기, 제목, 발신자, 수신자 등의 세부정보가 포함됩니다. view 매개변수는 관련 메시지에 채워지는 필드를 제어합니다. 기본적으로 (또는 THREAD_VIEW_MINIMAL 사용 시) 제목과 스니펫이 포함됩니다. THREAD_VIEW_METADATA_ONLY를 사용하여 제목과 스니펫을 제외합니다. 이 도구는 전체 메시지 본문을 반환하지 않습니다. 필요한 경우 스레드 ID와 함께 'get_thread' 도구를 사용하여 전체 메시지 본문을 가져오세요. 제외된 기준이 있는 스레드는 결과에 계속 표시될 수 있습니다. Gmail에서 일치하는 메일을 먼저 식별하기 때문에 이러한 현상이 발생합니다. 예를 들어 -is:starred를 검색하면 동일한 대화에 별표가 표시된 다른 이메일이 있더라도 별표가 표시되지 않은 메일이 하나 이상 포함된 경우 Gmail에서 전체 대화목록을 찾습니다.

다음 샘플은 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
}'

입력 스키마

SearchThreads RPC의 요청 메시지입니다.

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> - 특정 콘텐츠 유형 (첨부파일, 드라이브, YouTube, 문서)이 있습니다.
  • filename:<name> - 특정 이름 또는 유형의 첨부파일
  • "<word/phrase>" - 정확한 단어 또는 구문을 검색합니다. (예: "holiday", "holiday vacation")
  • +<word> - 단어와 정확히 일치합니다. (예: +holiday, +unicorn)
  • rfc822msgid:<id>: 특정 메일 ID 헤더입니다.
  • AROUND <distance> - 근처에 있는 단어를 찾습니다 (예: holiday AROUND 10 vacation).

라벨 및 카테고리:

  • label:<name> — 특정 라벨 아래 이 도구는 표시 이름이 아닌 라벨 ID를 허용합니다. list_labels 도구를 사용하여 ID를 가져옵니다.
  • 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

ListThreads 및 SearchThreads 응답에서 대화목록에 채워지는 필드를 제어하는 enum입니다.

열거형
THREAD_VIEW_UNSPECIFIED 하위 호환성을 위해 THREAD_VIEW_MINIMAL에 매핑됩니다.
THREAD_VIEW_METADATA_ONLY id, from, to, cc, date, labelIds를 반환합니다.
THREAD_VIEW_MINIMAL id, snippet, subject, from, to, cc, date, labelIds를 반환합니다.

출력 스키마

SearchThreads RPC의 응답 메시지입니다.

SearchThreadsResponse

JSON 표현 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
필드
threads[]

object (Thread)

대화목록 요약 목록입니다.
nextPageToken

string

후속 호출에서 다음 스레드 페이지를 가져오는 데 사용할 수 있는 토큰입니다. 결과가 더 있는 경우에만 표시됩니다. 쿼리와 일치하는 스레드 수가 page_size 한도를 초과하면 응답에 next_page_token이 포함됩니다. 결과의 다음 페이지를 가져오려면 다음 SearchThreadsRequest의 page_token 필드에 이 토큰을 전달하세요.
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

출력 전용입니다. 첨부파일 ID입니다. MessageFormat이 FULL_CONTENT인 경우에만 채워집니다.
htmlBody

string

이메일의 HTML 콘텐츠입니다. MessageFormat이 FULL_CONTENT인 경우에만 채워집니다.
attachments[]

object (AttachmentMetadata)

출력 전용입니다. 첨부파일입니다. MessageFormat이 FULL_CONTENT인 경우에만 채워집니다.
labelIds[]

string

메일에 첨부된 라벨의 ID입니다. 사용자 라벨과 INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT로 제한된 표준 시스템 라벨의 ID가 포함됩니다.

AttachmentMetadata

JSON 표현 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
필드
id

string

출력 전용입니다. 첨부파일의 ID입니다.
mimeType

string

첨부파일의 MIME 유형입니다.
filename

string

첨부파일의 파일 이름입니다.

도구 주석

파괴적 힌트: ❌ | 동일한 힌트: ✅ | 읽기 전용 힌트: ✅ | 오픈 월드 힌트: ❌

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

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