MCP Tools Reference: chatmcp.googleapis.com

도구: search_messages

키워드와 필터를 사용하여 Google Chat 메시지를 검색하고 마크다운 형식으로 반환합니다. 사용자가 액세스할 수 있는 모든 스페이스에서 작동하거나 특정 대화로 범위를 지정할 수 있습니다.

search_messages와 다른 검색 또는 읽기 도구 중 무엇을 사용할지 결정할 때는 다음 가이드를 따르세요.

  • 여러 스페이스에서 또는 알려진 대화 ID 없이 특정 메시지 콘텐츠, 키워드, 멘션, 링크, 발신자 또는 읽지 않은 메시지를 찾을 때는 search_messages를 사용합니다.
  • 특정 스페이스 또는 대화목록 ID를 알고 있고 메시지를 시간순으로 순차적으로 읽으려면 list_messages를 사용합니다.
  • search_conversations를 사용하여 스페이스 표시 이름 또는 참여자로 대화 ID와 같은 스페이스 메타데이터를 찾습니다 (메시지 콘텐츠가 아닌 메타데이터만 검색).

특정 필터 없이 searchParameters를 제공하면 사용자가 액세스할 수 있는 대화 전반의 최근 메시지가 반환됩니다.

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

curl 요청 
curl --location 'https://chatmcp.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_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

SearchMessagesRequest

JSON 표현 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
필드
searchParameters

object (SearchParameters)

필수 항목입니다. 검색에 사용할 검색 매개변수입니다.
pageSize

integer

선택사항입니다. 반환할 최대 결과 수입니다 (최대 100개). 지정하지 않으면 최대 25개가 반환됩니다.
pageToken

string

선택사항입니다. 이전 search_messages 호출에서 받은 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.

SearchParameters

JSON 표현 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
필드
keywords[]

string

선택사항입니다. 결과를 필터링하는 데 사용되는 키워드 집합입니다.
conversationId

string

선택사항입니다. search_conversations 도구에서 반환된 특정 대화 식별자로 검색 범위를 지정합니다. 형식은 spaces/{ID}입니다.
sender

string

선택사항입니다. 특정 사용자의 메시지를 필터링합니다. 발신자의 이메일 또는 리소스 이름을 사용할 수 있습니다. 사용자 리소스 이름은 users/{ID} 형식으로 지정됩니다. 여기서 {ID}은 사용자 ID 또는 이메일 주소일 수 있습니다.
isUnread

boolean

선택사항입니다. 호출 사용자가 읽지 않은 메시지를 필터링합니다.
hasLink

boolean

선택사항입니다. URL이 하나 이상 포함된 메시지를 필터링합니다.
startTime

string

선택사항입니다. 이 시간 이후에 생성된 메시지를 필터링합니다. 형식: ISO 8601 타임스탬프
endTime

string

선택사항입니다. 이 시간 이전에 생성된 메시지를 필터링합니다. 형식: ISO 8601 타임스탬프
mentionsMe

boolean

선택사항입니다. 호출 사용자를 명시적으로 언급하는 메시지를 필터링합니다.
conversationIncludesUser

string

선택사항입니다. 특정 사용자 이메일 또는 ID가 포함된 채팅 메시지 및 그룹 채팅 메시지를 필터링합니다.
spaceDisplayNames[]

string

선택사항입니다. 스페이스 이름 목록으로 필터링합니다. 스페이스 표시 이름은 부분적으로 일치합니다. 참고: 상위 5개의 일치 항목만 반환됩니다.
conversationTypes[]

enum (ConversationType)

선택사항입니다. 대화 유형별로 필터링합니다.
hasAttachment

boolean

선택사항입니다. 첨부파일이 하나 이상 포함된 메일을 필터링합니다. 참고: 이 필드는 개발 중이며 아직 일부 환경에서 지원되지 않을 수 있습니다.

ConversationType

대화 유형을 정의합니다.

열거형
CONVERSATION_TYPE_UNSPECIFIED 지정되지 않음.
NAMED_SPACE 이름이 지정된 스페이스
GROUP_CHAT 3명 이상의 사용자가 참여하는 그룹 채팅입니다.
DIRECT_MESSAGE 두 사람 간 또는 사람과 Chat 앱 간의 채팅 메시지입니다.

출력 스키마

Google Chat 메시지 검색에 대한 응답입니다. next_page_token이 채워진 경우 해당 토큰으로 SearchMessages 호출을 다시 호출하여 다음 결과 페이지를 가져올 수 있습니다.

SearchMessagesResponse

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

object (ChatMessage)

검색 기준과 일치하는 메시지 객체의 목록입니다.
nextPageToken

string

다음 페이지를 검색하기 위해 page_token으로 전송할 수 있는 토큰입니다. 이 필드를 생략하면 후속 페이지가 표시되지 않습니다.

ChatMessage

JSON 표현 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
필드
messageId

string

메시지의 리소스 이름입니다. 형식: spaces/{space}/messages/{message}
threadId

string

이 메일이 속한 대화목록입니다. 메시지가 대화목록에 포함되지 않은 경우 비어 있습니다. 형식: spaces/{space}/threads/{thread}
plaintextBody

string

마크다운 형식을 사용하는 메시지의 텍스트 본문입니다.
sender

object (User)

메시지 발신자입니다.
createTime

string

출력 전용입니다. 메시지가 생성된 타임스탬프입니다. 형식: ISO 8601 타임스탬프
threadedReply

boolean

메시지가 대화목록 답장인지 여부입니다.
attachments[]

object (ChatAttachmentMetadata)

메일에 포함된 첨부파일입니다.
reactionSummaries[]

object (ReactionSummary)

메시지에 포함된 이모티콘 반응 요약입니다.
quotedMessageMetadata

object (QuotedMessageMetadata)

출력 전용입니다. 이 메일에서 인용되거나 전달된 원본 메일에 관한 정보입니다. 참고: 이 필드는 개발 중이며 아직 일부 환경에만 제공될 수 있습니다.

사용자

JSON 표현 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
필드
userId

string

Chat 사용자의 리소스 이름입니다. 형식: users/{user}
displayName

string

Chat 사용자의 표시 이름입니다.
email

string

사용자의 이메일 주소입니다. 이 필드는 사용자 유형이 HUMAN인 경우에만 채워집니다.
userType

enum (UserType)

사용자 유형입니다.

ChatAttachmentMetadata

JSON 표현 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
필드
attachmentId

string

첨부파일의 리소스 이름입니다. 형식: spaces/{space}/messages/{message}/attachments/{attachment}
filename

string

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

string

콘텐츠 유형 (MIME 유형)입니다.
source

enum (Source)

첨부파일의 소스입니다.
driveFileId

string

출력 전용입니다. Google Drive 파일의 ID입니다. 소스가 DRIVE_FILE인 경우에만 채워집니다. Google Drive MCP와 함께 사용합니다.

ReactionSummary

JSON 표현 
{
  "emoji": string,
  "count": integer
}
필드
emoji

string

이모티콘 유니코드 문자열 또는 맞춤 이모티콘 이름입니다.
count

integer

연결된 이모티콘을 사용한 총 반응 수입니다.

QuotedMessageMetadata

JSON 표현 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
필드
messageId

string

출력 전용입니다. 인용되거나 전달된 원본 메일의 리소스 이름입니다. 형식: spaces/{space}/messages/{message}
lastUpdateTime

string

출력 전용입니다. 인용되거나 전달되기 전에 원본 메시지가 생성되거나 마지막으로 업데이트된 시점의 타임스탬프입니다. 형식: ISO 8601 타임스탬프
quoteType

enum (QuoteType)

출력 전용입니다. 견적 유형입니다.
plaintextBody

string

출력 전용입니다. 인용 또는 전달 시점의 원본 메시지 본문 텍스트 스냅샷입니다. FORWARD에는 마크다운을 사용하고 REPLY에는 일반 텍스트를 사용하여 형식이 지정됩니다.
sender

string

출력 전용입니다. 원본 메시지의 작성자 표시 이름입니다.
attachments[]

object (ChatAttachmentMetadata)

출력 전용입니다. 원본 메일에 포함된 첨부파일 FORWARD 견적 유형에만 채워집니다.
forwardedMetadata

object (ForwardedMetadata)

출력 전용입니다. 전달된 메시지의 소스 대화에 관한 메타데이터입니다. FORWARD 견적 유형에만 채워집니다.

ForwardedMetadata

JSON 표현 
{
  "conversationId": string,
  "conversationDisplayName": string
}
필드
conversationId

string

출력 전용입니다. 소스 대화의 리소스 이름입니다. 형식: spaces/{space}
conversationDisplayName

string

출력 전용입니다. 메시지가 전달된 시점의 원본 대화 표시 이름입니다. 이름이 지정된 스페이스의 경우 스페이스 이름입니다. 1:1 채팅 메시지의 경우 다른 참여자의 이름입니다. 이름이 지정되지 않은 그룹 채팅의 경우 구성원 이름을 기반으로 생성된 이름입니다.

UserType

Google Chat 사용자의 유형입니다.

열거형
USER_TYPE_UNSPECIFIED 지정되지 않음.
HUMAN 인간 사용자
APP 앱 사용자

소스

첨부파일의 소스입니다.

열거형
SOURCE_UNSPECIFIED Reserved.
DRIVE_FILE 파일이 Google Drive 파일입니다.
UPLOADED_CONTENT 파일이 Chat에 업로드됩니다.

QuoteType

메시지가 인용 답장인지 전달된 메시지인지 나타내는 인용 유형입니다.

열거형
QUOTE_TYPE_UNSPECIFIED Reserved. 정의되지 않은 견적 유형입니다.
REPLY 메시지가 동일한 대화목록에 있는 원본 메시지에 대한 인용 답장입니다.
FORWARD 메시지가 다른 대화의 원본 메시지 또는 동일한 대화의 다른 대화목록에서 전달됩니다.

도구 주석

도구 주석은 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/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly