Skip to content
Back to search

googlechat-py

Unofficial async Python client, CLI and MCP server for Google Chat's internal web API (cookie-based auth, no Google Cloud project required)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dzmitry-bahaslousky--googlechat-py/badge.svg)](/listings/dzmitry-bahaslousky--googlechat-py)

HTML

<a href="/listings/dzmitry-bahaslousky--googlechat-py"><img src="/api/listings/dzmitry-bahaslousky--googlechat-py/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need [`uv`](https://docs.astral.sh/uv/) and Google Chrome (Chrome is used only to sign in).

uv tool install git+https://github.com/dzmitry-bahaslousky/googlechat-py

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 111 lines
  1. # googlechat-py
  2. 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.
  3. Three ways to use it:
  4. - **`googlechat-mcp`** — an MCP server, so Claude (or another agent) can read and send your chats
  5. - **`gchat`** — a command-line tool
  6. - **`googlechat`** — an async Python library
  7. > ⚠️ 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.
  8. ## Install
  9. You need [`uv`](https://docs.astral.sh/uv/) and Google Chrome (Chrome is used only to sign in).
  10. ```bash
  11. uv tool install git+https://github.com/dzmitry-bahaslousky/googlechat-py
  12. ```
  13. ## Update
  14. ```bash
  15. uv tool upgrade googlechat-py
  16. ```
  17. 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.
  18. ## Sign in
  19. ```bash
  20. googlechat-mcp login
  21. ```
  22. 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.
  23. ## Use with Claude Code
  24. ```bash
  25. claude mcp add --scope user googlechat -- googlechat-mcp
  26. ```
  27. Claude can then list chats (including which have unread messages), and read and search messages. That's all by default.
  28. To also let Claude send, reply, react, and edit or delete your own messages, turn on write tools:
  29. ```bash
  30. claude mcp add --scope user -e GCHAT_MCP_WRITE=1 googlechat -- googlechat-mcp
  31. ```
  32. > ⚠️ 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.
  33. ## Use from the command line
  34. ```bash
  35. gchat spaces -n 10 # your chats
  36. gchat sections one # chats in one of your sidebar sections
  37. gchat unread # chats with messages you haven't read
  38. gchat read SPACE_ID -n 5 # latest threads in a chat
  39. gchat thread SPACE_ID THREAD_ID # one whole thread
  40. gchat search "release" # search all chats
  41. gchat send SPACE_ID "Hello" # asks before posting
  42. gchat reply SPACE_ID THREAD_ID "On it"
  43. gchat --json spaces # JSON output for scripts
  44. ```
  45. Run `gchat --help` for all commands. Commands that post or change something as you ask for confirmation first; in scripts, add `--yes`.
  46. ## Use from Python
  47. ```python
  48. import asyncio
  49. from googlechat import GoogleChatClient
  50. async def main():
  51. async with GoogleChatClient.from_storage() as chat:
  52. spaces = await chat.spaces.list(page_size=10)
  53. for m in await chat.messages.list(spaces[0].id):
  54. print(m.sender.name, m.text)
  55. asyncio.run(main())
  56. ```
  57. Available: `chat.spaces`, `chat.messages`, `chat.members`, `chat.reactions`, `chat.users`.
  58. ## Settings
  59. | Environment variable | Default |
  60. |---|---|
  61. | `GCHAT_CONFIG_DIR` | `~/.config/googlechat-mcp` |
  62. | `GCHAT_COOKIES` | `$GCHAT_CONFIG_DIR/cookies.json` |
  63. | `GCHAT_PROFILE` | `$GCHAT_CONFIG_DIR/browser-profile` |
  64. | `GCHAT_MCP_WRITE` | off; `1` turns on the MCP server's write tools |
  65. ## Troubleshooting
  66. | Problem | Fix |
  67. |---|---|
  68. | `Not signed in` or `Session expired` | Run `googlechat-mcp login` |
  69. | Errors on one feature only | Google probably changed the API — see [purple-googlechat](https://github.com/EionRobb/purple-googlechat) |
  70. ## Development
  71. ```bash
  72. uv sync
  73. uv run pytest # offline tests, no account needed
  74. ```
  75. ## Credits
  76. Protocol from [EionRobb/purple-googlechat](https://github.com/EionRobb/purple-googlechat).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.