MCP Tools Reference: gmailmcp.googleapis.com

도구: search_threads

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

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

다음 샘플은 curl를 사용하여 search_threads MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청 
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \
--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
}
필드

통합 필드 _page_size.

_page_size는 다음 중 하나여야 합니다.
pageSize

integer

선택사항입니다. 반환할 최대 스레드 수입니다. 지정하지 않으면 기본값은 20입니다. 허용되는 최댓값은 50입니다.

통합 필드 _page_token.

_page_token는 다음 중 하나여야 합니다.
pageToken

string

선택사항입니다. 목록에서 특정 결과 페이지를 가져오는 페이지 토큰입니다. 첫 번째 페이지를 가져오려면 비워 둡니다. 이는 주로 페이지로 나누기를 사용하여 이전 SearchThreads 호출이 중단된 지점부터 결과를 계속 가져오는 데 사용됩니다. 특히 쿼리와 일치하는 스레드 수가 page_size 한도를 초과하는 경우에 유용합니다.

통합 필드 _query.

_query는 다음 중 하나여야 합니다.
query

string

선택사항입니다. 스레드를 필터링하는 쿼리 문자열입니다. 이 도구를 사용하려면 자연어 쿼리를 Gmail 구문 쿼리로 사전 변환해야 합니다. 생략하면 모든 스레드 (기본적으로 스팸 및 휴지통 제외)가 나열됩니다.

카테고리별 지원되는 연산자:

보낸사람 및 수신자: from: - 특정 사용자가 보낸 메일 to: - 특정 사용자에게 보낸 이메일 cc: - 참조에 특정 사용자를 추가합니다. 숨은참조: - 숨은참조에 포함된 특정 사용자입니다. deliveredto: - 특정 주소로 배송됨 list: - 특정 메일링 리스트에서

시간 및 날짜: after:YYYY/MM/DD / newer:YYYY/MM/DD - 특정 날짜 이후에 수신됨 before:YYYY/MM/DD / older:YYYY/MM/DD - 특정 날짜 이전에 수신됨 older_than: - 기간보다 오래된 항목 (예: 1y, 2d) newer_than: - 특정 기간보다 최신인 항목

콘텐츠: subject: - 제목에 포함된 단어 has: - 특정 콘텐츠 유형 (첨부파일, 드라이브, YouTube, 문서)이 있습니다. filename: - 특정 이름 또는 유형의 첨부파일 '<단어/구문>' - 정확한 단어나 구문을 검색합니다. (예: '휴일', '휴가') + - 단어를 정확히 일치시킵니다. (예: +holiday, +unicorn) rfc822msgid: - 특정 메시지 ID 헤더입니다. AROUND - 서로 가까운 단어를 찾습니다 (예: holiday AROUND 10 vacation).

라벨 및 카테고리: label: - 특정 라벨 아래에 있습니다. 이 도구는 표시 이름이 아닌 라벨 ID를 허용합니다. list_labels 도구를 사용하여 ID를 가져옵니다. category: - 카테고리 (기본, 소셜, 프로모션, 업데이트, 포럼, 예약, 구매) in:

상태: is: - 상태 (중요, 별표표시됨, 읽지 않음, 읽음, 음소거)별로 검색합니다.

크기: size: - 바이트 단위의 특정 크기입니다. larger: / smaller: - 크기보다 크거나 작음 (예: 10MB의 경우 10M)

논리 및 그룹화: AND - 모든 기준과 일치합니다 (기본 동작). OR 또는 { } - 하나 이상의 기준과 일치합니다 (예: from:amy OR from:david, {from:amy from:david}). - (빼기) - 기준 제외 (예: -영화) ( ) - 여러 검색어를 그룹화합니다 (예: 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입니다.

출력 스키마

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

SearchThreadsResponse

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

object (Thread)

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

string

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

스레드

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
  ]
}
필드
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인 경우에만 채워집니다.

도구 주석

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