Skip to main content
Glama

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 chats

  • gchat — a command-line tool

  • googlechat — 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-py

Related MCP server: agent-chrome

Update

uv tool upgrade googlechat-py

This 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 login

Chrome 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-mcp

Claude 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 scripts

Run 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

GCHAT_CONFIG_DIR

~/.config/googlechat-mcp

GCHAT_COOKIES

$GCHAT_CONFIG_DIR/cookies.json

GCHAT_PROFILE

$GCHAT_CONFIG_DIR/browser-profile

GCHAT_MCP_WRITE

off; 1 turns on the MCP server's write tools

Troubleshooting

Problem

Fix

Not signed in or Session expired

Run googlechat-mcp login

Errors on one feature only

Google probably changed the API — see purple-googlechat

Development

uv sync
uv run pytest      # offline tests, no account needed

Credits

Protocol from EionRobb/purple-googlechat.

Available Tools

10 tools
get_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

    B3.4/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables 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.
      13
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      7
      16 npm
      MIT