io.github.mmedum/google-chat-mcp

Invite someone in your organization into a space by email address, or add a Google Group. In a space that admits people from outside the organization, an address the organization's directory does not know is refused [blocked], and so is every Google Group, since a group brings in its outside members and anyone added to it later: add_external_member adds those. Someone already in the space is reported as an error rather than as a success, because the membership that exists belongs to whoever invited them first. Everyone joins as an ordinary member: Google ignores a role given here, silently. Set dry_run to see the request body without inviting anyone.

React to a message with a single unicode emoji. Reacting the same way twice is not an error: the reaction that is already there is returned instead.

Add a custom emoji to your organization from an image on this machine. Everyone in the organization can then use it, so the name is worth agreeing first. The image must be a square PNG, JPEG or GIF, 64 to 500 pixels, under 256 KB.

Start an unnamed group conversation with 2 to 20 people. Leave yourself out of member_emails: Google adds the signed-in account. A group chat cannot have a name; use create_space when you need one. Set dry_run to see the request body without creating anything.

Add a custom section to your own Chat sidebar. Google does not merge sections by name, so two calls leave two sections with the same label: list_sections first if you mean to reuse one. Sections are per-user and change nobody else's view. Set dry_run to see the request body first. Needs the chat.users.sections scope.

Create a named space, with up to 20 initial members or none at all. Leave yourself out of member_emails: Google adds the signed-in account. A space of your own is fine — invite people later with add_member. A space is created private; set_space_audience opens one to an audience. Set dry_run to see the request body without creating anything.

Save a message's attachment to the server's local directory. Name the message; if it carries more than one file, pass attachment_name from get_message. The result says where the file landed. A Google Drive attachment is refused with its file id: those bytes belong to Drive, not Chat. This needs the server to have been started with GCM_LOCAL_DIR.

Find the direct message with one person, and start one when there is none yet. Returns the space to pass to send_message. A newly started direct message is empty, so the other person sees nothing until a message is posted in it.

Turn a Google Group's email address into its groups/{id} name, which add_member takes as group_name. Chat names a group only by that id. Looked up through Cloud Identity, which shows only the groups this account can see. Google answers an address no group has the same way as a group kept to its own members, so a refusal cannot say which.

Find the group chats whose members are exactly you and the people you name. Use it before create_group_chat to reuse an existing chat rather than starting a second one with the same people. A chat with one extra member does not match. For a one-to-one conversation use find_direct_message.

Read your own Chat presence: active, idle, away or do not disturb, with any custom status. Yours only — Google's endpoint answers for the signed-in account and there is no way to ask about anyone else.

Read one custom emoji by its resource name, which list_custom_emojis reports.

Read one membership: who or what it is, their role, and whether they have joined. list_members answers who is in a space; this answers what a membership is, which is what to check before changing a role or removing someone — a membership can name a Google Group, and removing that one removes everyone in the group from the space.

Fetch a single message by its resource name (spaces/{space}/messages/{message}). Reaction summaries are inline; reactions_paged true means there were too many to inline and list_reactions has the detail. Attachments are listed with the name download_attachment takes. links is what the text links to — a message whose body is a link names the target there and nowhere else — and formatted_text is the same body with Chat's markup left in. quote is the message this one replies to or forwards, as it read when it was quoted; a forward carries the whole snapshot, because the space it came from is often one you cannot read.

Read recent messages from a space. Returns up to limit messages (default 20, max 100), newest first; page with page_token and next_page_token. Keep paging while next_page_token is non-null: an EMPTY result with a token still on it does not mean the space is empty, because Google applies the page size before it filters. Sender email is the one Chat sends, or a People API lookup when Chat sends none, and is null when both come back empty. Each message carries links: what its text links to, which Chat keeps out of the body, so a message reading as a bare word may be a link to something. quote is what a message replies to or forwards, which Chat also keeps out of the body. Each message also carries its files, reaction counts, when it was edited and whether it replies in its thread; a message that is only a file has empty text.

Fetch one Google Chat space by its resource name. Use it to identify an unnamed direct message or group chat, or to confirm a space's metadata before writing to it.

One event from a space by its resource name, which list_space_events reports. The payload is the resource as it is now, not as it was: an event about a message that has since been edited names the message, and get_message returns the current text.

Read what Chat tells you about a space: which messages notify you, and whether the space is muted. Your own setting, not the space's.

Read how far you have read in a space. This is your own state, not the space's: two people reading the same space get different answers. Only top-level messages count, not thread replies.

Read one thread's messages, oldest first. Give the parent space_id and the thread_name (spaces/{space}/threads/{thread}), which every message carries as thread_id. Default limit 50, max 100; page with page_token and next_page_token. A non-null next_page_token means the thread is longer than what came back, so do not read the result as the whole thread. Each message carries its links, what it quotes, its files and reaction counts, and when it was edited.

Read how far you have read in one thread. Your own state, as with a space.

List your organization's own emoji, the ones people type as :shortcodes:. Custom emoji exist only on Google Workspace accounts and only when an administrator has turned them on.

List the members of a Google Chat space: people, Google Groups, and anyone invited who has not joined yet. Every row carries kind (HUMAN or GROUP) and state (JOINED, INVITED, NOT_A_MEMBER), so check state before reporting someone as present. People come back with the email Chat sends, or one looked up through the People API when Chat sends none; a Google Group comes back with the address and name Cloud Identity gives it, or with only groups/{id} when that lookup is not granted. Default 50 entries; pass limit (1-200) to widen, and page with page_token and next_page_token. A non-null next_page_token means the space has more members than came back, so do not report the result as the whole membership.

List the messages pinned in a space. A pin is how a space marks something worth keeping to hand, so this is a good first read for what a space is about.

List the reactions on a single message: who reacted and with what. Default limit 50, max 200; page with page_token and next_page_token. Custom emoji are left out, having no character to show.

List the spaces filed under a section. Pass section_name to read one section, space_id to find which section a single space sits in, or both to check one against the other; at least one is required. A non-null next_page_token means limit cut the listing short, so page rather than treat it as the whole section. Needs the chat.users.sections.readonly scope.

List the sections in the caller's own Chat sidebar: the system ones ('(direct messages)', '(spaces)', '(apps)') plus any custom ones they made. Sections are per-user and change nobody else's view. A non-null next_page_token means more sections exist beyond limit. Needs the chat.users.sections.readonly scope.

What changed in a space over the last 28 days: messages posted, edited or deleted, people joining or leaving, reactions, and edits to the space itself. Name at least one event type. Events come oldest first and each names the resources it covers, which you read with get_message, get_member or get_space. Google keeps 28 days and no more, and it answers a busy space with batch events covering several changes at once.

List Google Chat spaces (direct messages, group chats, named spaces) the authenticated user belongs to. Defaults to 50 entries; pass limit (1-200) to widen and space_type ('SPACE' | 'DIRECT_MESSAGE' | 'GROUP_CHAT') to narrow, and page with page_token and next_page_token. A non-null next_page_token means the account is in more spaces than came back. Use this to find a space's resource name before reading its messages.

Mark a space as read up to now, clearing its unread badge for you and nobody else. Google pulls the mark back to the newest message's own time, so the answer reports what it recorded.

Rewind your read mark in a space, so every top-level message after from_time is unread again. Pass the timestamp of the message you want to come back to; get_messages reports it. Affects you and nobody else.

File a space under a section in your own sidebar. Every space already sits in some section, a default one until you move it, so this both files and re-files, and reports moved false when the space is already where you want it. For a bulk sort, read each section once with list_section_items and pass the item_name it gives you: that skips the per-space lookup. Set dry_run to see which section the space would leave without writing. Needs the chat.users.sections scope.

Pin a message in its space, so everyone in the space sees it in the pinned list. The space is taken from the message name. Pinning is visible to everyone.

Move a section within your sidebar. Pass exactly one of sort_order (absolute, 1 and up) or relative_position (START or END). Prefer relative_position when arranging several: Google documents sort_order as inserting at that rank and shifting the rest down, but a run of absolute inserts does not settle where that implies, so build an order by moving each to START in reverse. Set dry_run to see the request body first. Needs the chat.users.sections scope.

Delete a reaction. Pass reaction_name on its own, or message_name with emoji and user_email to look it up first. The lookup matches on the reactor's email address, so it fails rather than reporting nothing to delete when someone who reacted cannot be resolved: a silent no was the one answer it must not give. Removed false means there was no such reaction.

Change a custom section's label. Only custom sections can be renamed; Google refuses a patch against a system one. Set dry_run to see the patch body first. Needs the chat.users.sections scope.

Search Google Chat message history. Two searches in one tool. Pass query and Google searches every space you can see, matching whole words; narrow it with space_id, sender_email, mentions_me, has_attachment, has_link, unread_only and a time window. Pass regex instead and this server scans one space itself, which is the only way to match a pattern or part of a word — it needs space_id, reads pages of history, and takes none of the filters. Prefer query. If cap_reached is true the answer is partial; if unparsed is non-zero it is incomplete, and saying the space is empty would be wrong. Each hit carries its links, what it quotes, its files and reaction counts, and when it was edited.

Look someone up across the caller's Workspace directory and their own contacts, and get their email address. Each hit says which source produced it. Directory hits are remembered, so a later get_messages or list_members resolves the same person without another lookup. Use it to turn a name or a fragment of one into the email address the other tools take.

Search the named Google Chat spaces you are a member of by display name, or every space in the Workspace with use_admin_access. Use find_group_chats for a group chat, which this cannot return. Matching is by word prefix. Without admin access Google returns a single page of up to 100 and no total.

Post a text message to a Chat space, a group chat or a direct message. The body is posted exactly as given: nothing is added to it, and nothing in it is rewritten. To @mention someone, put <users/their@address> in the text yourself; a mention of everyone in the space, <users/all>, is refused [blocked], since it notifies every member. Pass thread_name to reply in an existing thread, which every message carries as thread_id. Set dry_run to see the request body without posting. The post carries a client-assigned id, so this server's own retries cannot leave two copies — but calling the tool again after an error can, because that is a new post. Read the space first if you are unsure. To send a file, upload it with upload_attachment first and pass the token it returns.

Set your own Chat presence to ACTIVE, AWAY or DO_NOT_DISTURB. Do not disturb needs an expiry — minutes or until — which Google requires and caps at a year. Other people see this, so it is worth asking before silencing someone's notifications on their behalf.

Set the text and emoji beside your name in Chat, or clear it. Google wants both together and refuses one without the other; a custom emoji is not accepted here, only a Unicode one. An expiry is optional, unlike do-not-disturb's. Everyone who sees you in Chat sees this.

Remove a message's pin. Takes the message, not the pin: Google gives a pin the message's own id. A message that was not pinned reports unpinned false rather than failing.

Make a manager or an assistant manager an ordinary member of a space again: role MEMBER. Demoting the last manager may leave nobody able to administer the space. Making someone a manager is refused [blocked] here; promote_member does it. Role is the only thing this changes. Set dry_run to see the request body without sending it.