Google Chat MCP

Permanently deletes a message. With user authentication the user can delete their OWN messages; space managers can also delete others' messages in spaces they manage — otherwise PERMISSION_DENIED (a Chat permission rule, not a missing scope). If the message started a thread that has replies, the delete fails with FAILED_PRECONDITION; force=true deletes the replies too but works only with app (service-account) authentication. Deletion cannot be undone — read the message with get_message first if its content matters. Returns an empty object on success.

Finds the EXISTING direct-message space between the authenticated user and another user, returning the space (name spaces/<id>) to send_message into. Returns HTTP 404 when no DM with that user exists yet — this tool cannot create one (creating DMs needs spaces.setup via raw_request). The user can be a Google user id (users/123...) or an email address.

Fetches metadata of one message attachment by its resource name (from a message's attachment[].name): contentName (filename), contentType (MIME), source (DRIVE_FILE or UPLOADED_CONTENT), downloadUri/thumbnailUri (short-lived, for a signed-in browser user — not for server-side download) and attachmentDataRef. NOTE the auth split: this dedicated endpoint accepts only APP (service-account) authentication — with user credentials it returns an error, but the SAME metadata is already embedded in get_message's attachment[] field, so user-auth flows should read it there. Downloading raw bytes goes through the media endpoint (v1/media/<resourceName>?alt=media) and uploading new attachments through the upload endpoint — both outside this server's tools.

Fetches one message by its full resource name: text, formattedText, sender, createTime/lastUpdateTime, thread.name (reply target for send_message), attachment[] metadata (name, contentName, contentType, downloadUri, attachmentDataRef) and emojiReactionSummaries. Also resolves custom-id names (spaces/<space>/messages/client-<id>) for messages sent with message_id. Deleted messages return deletionMetadata instead of content.

Returns one space's details: displayName, spaceType, spaceDetails (description/guidelines), spaceThreadingState (THREADED_MESSAGES = replies go into threads, otherwise the space is flat), membershipCount, createTime and settings. Use it to check the threading model before send_message with a thread, or to confirm a space id before writing into it.

Lists memberships in a space: each membership's name (spaces/<space>/members/<member> — the handle manage_members needs), member (users/<id>, displayName, type HUMAN|BOT), role (ROLE_MEMBER or ROLE_MANAGER) and state (JOINED, INVITED, NOT_A_MEMBER). role filters to managers or members; show_invited includes invited-but-not-joined users, show_groups includes Google Groups. Requires the chat.memberships.readonly (or chat.memberships) scope and membership in the space.

Lists messages in a space (including messages from blocked members and spaces): name, text, sender, createTime, thread.name, attachment metadata and emoji reaction summaries. Filters are the API's only two: created_after (createTime) and thread_name (one thread's messages) — there is no text search, match client-side. order defaults to ascending by createTime; show_deleted includes tombstones of deleted messages. Poll incrementally with created_after + page_token instead of re-listing history. Requires the chat.messages.readonly (or chat.messages) scope and works only with user authentication.

Lists the spaces the authenticated user is a member of: name (spaces/<id>), displayName (empty for direct messages), spaceType (SPACE = named room, GROUP_CHAT, DIRECT_MESSAGE), spaceThreadingState and timestamps. This is the discovery entry point — space names from here feed every other tool. space_type narrows the listing server-side; there is no text search here — match displayName client-side, or use search_spaces (Workspace admin only). Paginate with page_token from nextPageToken; results are unordered.

Membership management in a space — WORKS ONLY WITH SUFFICIENT ACCESS: the authenticated user needs the chat.memberships scope, and add/update_role/remove additionally require them to be a space MANAGER (otherwise PERMISSION_DENIED — a Chat role rule, not a network problem; check their role via list_members). action=get reads one membership by member_name. action=add invites/adds a human user (space + user, optional role=manager); in DMs and group chats members cannot be added. action=update_role switches a membership between member and manager (member_name + role). action=remove deletes the membership — the user is kicked from the space immediately and this is not undoable from here (re-add creates a fresh invitation). Google Groups and Chat-app memberships are managed via raw_request.

Emoji reactions on a message, as the authenticated user. action=add puts a unicode emoji (the emoji character itself, e.g. "👍" or "🎉" — not :shortcode:) on the message; adding the same emoji twice fails with ALREADY_EXISTS. action=list returns who reacted with what — each reaction's name (spaces/.../reactions/<id>), emoji and user; filter with emoji to one emoji's reactions. action=remove deletes ONE reaction by its full reaction_name from list — only the authenticated user's own reactions can be removed (someone else's returns PERMISSION_DENIED). Custom (workspace) emoji need raw_request with emoji.customEmoji. Scopes: chat.messages.reactions (add/remove; .create suffices for add-only) or chat.messages.reactions.readonly (list).

Escape hatch to call any Google Chat API v1 path directly, for requests the typed tools don't cover — e.g. creating a space (path "v1/spaces", method POST, body {"spaceType":"SPACE","displayName":"..."}), setting up a DM ("v1/spaces:setup"), custom-emoji reactions, Google Group memberships, space events ("v1/spaces/<id>/spaceEvents"), or updating a space ("v1/spaces/<id>" PATCH with a query updateMask). The path may carry a query string (e.g. "v1/spaces/AAA/members?showInvited=true"). The Bearer token is added automatically; the method defaults to GET. Not for media: attachment upload/download use different endpoints (upload/v1, media/v1) that this server does not proxy.

Server-side search over ALL named spaces in the Workspace organization — including ones the caller is not a member of. ADMIN-ONLY: the call runs with useAdminAccess=true and requires a Google Workspace administrator authorized with the chat.admin.spaces or chat.admin.spaces.readonly scope; anyone else gets PERMISSION_DENIED — fall back to list_spaces and match displayName client-side. query uses the API's search syntax and MUST contain customer = "customers/my_customer" AND spaceType = "SPACE"; add displayName:"text" for name search, e.g. customer = "customers/my_customer" AND spaceType = "SPACE" AND displayName:"onboarding". order_by accepts membership_count.joined_direct_human_user_count, last_active_time or create_time with ASC/DESC.

Sends a text message to a space AS THE AUTHENTICATED USER (their name and avatar; needs the chat.messages.create or chat.messages scope, and the user must be a member of the space). Text supports Chat markup: *bold*, _italic_, ~strike~, `code`, <https://url|link>, <users/123> mentions. Threads: pass thread_name (from a message's thread.name) or a stable thread_key of your choosing to reply in a thread; by default a missing thread falls back to starting a new one — set reply_option="or_fail" to error instead. In non-threaded spaces the thread params are ignored by the API. message_id (must start with "client-") makes the send addressable later without storing the returned name — reuse of an id fails with ALREADY_EXISTS, which also makes accidental duplicate sends detectable. Returns the created message with name, thread.name and createTime. A send is NEVER retried after a 5xx/timeout: check with list_messages before re-sending. Cards (cardsV2) are app-auth-only — out of scope; use raw_request with a Chat-app token.

Replaces the text of an existing message (updateMask=text; the previous text is overwritten, not appended). With user authentication only the authenticated user's OWN messages can be edited — editing someone else's returns PERMISSION_DENIED, a Chat rule, not a missing scope. The message keeps its name and thread; lastUpdateTime is set and clients show an Edited marker. Updating cards or accessory widgets needs app auth via raw_request.