googlechat-mcp
Reads and sends Google Chat messages using the signed-in user's own browser session, exposing tools to list chats and sidebar sections, read threads, search messages across chats, and optionally (with write tools enabled) send, reply, react to, and edit or delete the user's own messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@googlechat-mcp show my 10 most recent Google Chat conversations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
googlechat-py
Use Google Chat from Python, the command line, or an AI agent — signed in with your own browser session. No Google Cloud project, no OAuth app, no admin rights.
Three ways to use it:
googlechat-mcp— an MCP server, so Claude (or another agent) can read and send your chatsgchat— a command-line toolgooglechat— an async Python library
⚠️ This uses Google Chat's private web API, the one chat.google.com itself uses. It is not official and can break whenever Google changes it. Check that your organization allows this before relying on it.
Install
You need uv and Google Chrome (Chrome is used only to sign in).
uv tool install git+https://github.com/dzmitry-bahaslousky/googlechat-pyRelated MCP server: agent-chrome
Update
uv tool upgrade googlechat-pyThis updates the library, gchat and googlechat-mcp together to the latest commit on main. Restart Claude Code afterwards so it starts the new MCP server. Your saved login is kept.
Sign in
googlechat-mcp loginChrome opens chat.google.com. Sign in as usual; the window closes by itself. Run the same command again when the session expires — it first tries to refresh silently. googlechat-mcp logout removes the saved login.
Use with Claude Code
claude mcp add --scope user googlechat -- googlechat-mcpClaude can then list chats (including which have unread messages), and read and search messages. That's all by default.
To also let Claude send, reply, react, and edit or delete your own messages, turn on write tools:
claude mcp add --scope user -e GCHAT_MCP_WRITE=1 googlechat -- googlechat-mcp⚠️ Messages Claude reads are written by other people. A message can try to trick Claude into posting or deleting something as you. With write tools on, keep Claude Code's approval prompts on for them.
Use from the command line
gchat spaces -n 10 # your chats
gchat sections one # chats in one of your sidebar sections
gchat unread # chats with messages you haven't read
gchat read SPACE_ID -n 5 # latest threads in a chat
gchat thread SPACE_ID THREAD_ID # one whole thread
gchat search "release" # search all chats
gchat send SPACE_ID "Hello" # asks before posting
gchat reply SPACE_ID THREAD_ID "On it"
gchat --json spaces # JSON output for scriptsRun gchat --help for all commands. Commands that post or change something as you ask for confirmation first; in scripts, add --yes.
Use from Python
import asyncio
from googlechat import GoogleChatClient
async def main():
async with GoogleChatClient.from_storage() as chat:
spaces = await chat.spaces.list(page_size=10)
for m in await chat.messages.list(spaces[0].id):
print(m.sender.name, m.text)
asyncio.run(main())Available: chat.spaces, chat.messages, chat.members, chat.reactions, chat.users.
Settings
Environment variable | Default |
|
|
|
|
|
|
| off; |
Troubleshooting
Problem | Fix |
| Run |
Errors on one feature only | Google probably changed the API — see purple-googlechat |
Development
uv sync
uv run pytest # offline tests, no account neededCredits
Protocol from EionRobb/purple-googlechat.
Available Tools
10 toolsget_user_statusA
Do-not-disturb state and custom status of users (ids from list_members).
Users Google returns no status for (e.g. bots) are listed under no_status.
Inputs: user_ids (required). Returns: result
list_membersB
List members of a space or DM.
Inputs: space_id (required), is_dm, page_size. Returns: result
list_sectionsA
List your sidebar sections in sidebar order, each with its chats.
name (any case) or a section id limits it to that section.
Inputs: name. Returns: result
list_space_filesC
List files, Drive items and links shared in the latest page_size threads.
Inputs: space_id (required), is_dm, page_size. Returns: result
list_spacesC
List spaces, group chats and DMs, most recently active first.
Inputs: page_size. Returns: result
list_unreadA
List the page_size most recently active chats with messages you haven't read.
A chat counts as unread when it has messages newer than your last_read_time or new replies in a thread you follow. Google gives no count of unread messages. Use read_messages and compare create_time with last_read_time to see what is new. Reading here does not mark anything read.
Inputs: page_size. Returns: result
read_messagesA
Read the latest threads of a space or DM: each thread's first message plus its
newest replies replies, with Drive files, attachments and links.
space_id and is_dm come from list_spaces; in every tool, is_dm may be left out and is then looked up. page_size is the number of threads. Use read_thread for every message of one thread.
Inputs: space_id (required), is_dm, replies, page_size. Returns: result
read_threadB
Read every message of one thread (or only its newest limit), oldest first.
Inputs: space_id (required), thread_id (required), is_dm, limit. Returns: result
search_messagesA
Search messages server-side across all chats, like Chat's search box.
space_id (+ is_dm) limits it to one chat. since/until are ISO dates or datetimes (e.g. "2026-11-01"; no timezone means UTC). order: "newest" or "relevance". Each hit includes its space_id and thread_id.
Inputs: query (required), is_dm, order, since, +3 more. Returns: result
sign_inA
Sign in to Google Chat or refresh an expired session. Tries a silent refresh from the saved browser profile first; if that fails, opens a Chrome window for the user to sign in (waits up to 10 minutes). Call this when other tools report the user is not signed in or the session expired.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target a distinct query shape: list_spaces (all spaces), list_unread (unread filter), list_sections (sidebar grouping), and search_messages (server-side search) are separable by their descriptions. The main overlap is read_messages vs read_thread and list_spaces vs list_sections, but the docs explicitly clarify thread-level vs message-level reading and section-grouped vs flat listing.
Nearly all names follow a verb_noun pattern (list_spaces, read_messages, search_messages, list_space_files, list_members, get_user_status). Minor deviations: list_unread omits the noun, and sign_in uses a verb+particle rather than verb_noun, but the set is still highly predictable.
10 tools is well-scoped for a chat client, covering listing, reading, searching, file/member lookup, and auth. Each tool earns its place and there is no filler.
The surface is entirely read-only: there is no send_message, reply, create space, or mark-as-read operation, which are core lifecycle actions for a Google Chat client. An agent asked to actually participate in chat will hit a dead end despite rich reading coverage.
Maintenance
Related MCP Connectors
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Let your AI agent operate any website through a real, logged-in browser session.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables interaction with Google Chat via MCP using the internal Dynamite API, allowing listing spaces, reading and sending messages, and managing DMs. No Google Cloud Console setup required.13MIT
- AlicenseNot gradedqualityCmaintenanceLets local AI agents drive the Chrome browser a user already has open, including signed-in sessions, by listing tabs, reading page text and actionable elements, then clicking, filling, selecting, scrolling, navigating, and capturing viewport screenshots without exporting cookies. Runs as a dependency-free local stdio process over Native Messaging, with per-tab leases, automatic reconnection, and pause/write-action controls.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to drive your own signed-in ChatGPT web account — asking questions, continuing chats, attaching files, toggling thinking or web search, creating images, transcribing recordings of any length, reading replies aloud, and managing conversations, memories and projects. It runs against a local Chrome tab on chatgpt.com and reports live progress and step-named errors back to the client.2MIT
- AlicenseAqualityBmaintenanceEnables AI agents to list spaces, read and search Google Chat conversations, and send messages or thread replies by driving the Chat web app in a signed-in Chrome profile, with no Google Chat API, OAuth app or Cloud project required.716 npmMIT