An MCP server that connects Claude Desktop to Google Chat. It is designed to run locally on each user's machine: Claude Desktop spawns the server automatically and communicates with it over stdio, so no separate process or network endpoint is needed.
Key features
MCP Server for trustly use Claude connected to Google Chat
スター
4
ツール
—
稼働率
—
Per-space allowlist: only the spaces you list are reachable, each with read access, write access or both (independent of each other).
No direct messages: sending to DMs and group chats is blocked.
Separate tools for interactive and automated sends: send_message posts only to regular spaces and is meant to require your approval in the client; send_message_unattended posts only to spaces marked :unattended, for scheduled tasks. When the client supports it, send_message also asks you to confirm the exact text and target space.
Your own identity: each user authenticates with their own Google account, so messages come from the real person, not a shared bot.
See docs/configuration.md for everything that can be configured, and its security implications.
Available tools
Tool
Permission
Description
list_spaces
—
List configured spaces with their r/w flags
get_space
read
Get details of a space
list_messages
read
List messages in a space (optional filter)
send_message
write
Send a message to a space without :unattended (see Sending messages)
send_message_unattended
write
Send a message to a :unattended space, without confirmation (for scheduled tasks)
list_members
read
List members of a space
chat_auth_status
—
OAuth token status and expiry warning (works without a valid token)
On Windows with WSL, this path is inside the WSL filesystem (see below).
2. Installing WSL on Windows
Skip this section on Mac or Linux.
Open PowerShell as Administrator and run:
wsl --install
This installs WSL 2 with Ubuntu. A system restart is required.
After restarting, Ubuntu launches automatically. Create your user when prompted.
Inside the Ubuntu terminal, install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
Create the config folder and copy the client_secrets.json downloaded earlier:
mkdir -p ~/.config/google-chat-mcp
# Copy the file from Windows (replace "YourUser" with your Windows username):
cp /mnt/c/Users/YourUser/Downloads/client_secrets*.json ~/.config/google-chat-mcp/client_secrets.json
First run: OAuth authentication
Run this command once, in a terminal on your machine, to authorise access to your Google account — it is a separate CLI step, not something Claude runs for you, and it must be done before Claude Desktop is configured to start the server:
A browser window will open. Sign in with your Google account and grant access. The token is saved to ~/.config/google-chat-mcp/token.json and refreshed automatically on subsequent runs. Its structure matches token.example.json in this repo.
Finding space IDs
To configure which spaces are accessible, you need their resource name (e.g. spaces/AAABBBCCC). There are two ways to find it.
git clone https://github.com/nuccio/google-chat-mcp
cd google-chat-mcp
uv pip install -e ".[dev]"
For running tests, including integration tests against real Google Chat spaces, see tests/README.md. To try latest in Claude Desktop before promoting it to stable, see docs/manual-testing.md.
Release and branch policy
Two tags separate the version people use every day from the one being tried:
Tag
Points to
How it moves
latest
the most recent commit on main whose automated tests passed
automatically, when the tests on main pass
stable
the last version tried in a real client and known to work
by hand, after trying latest
Clients configured with stable are not affected by bugs that the automated tests did not catch: a change reaches them only after someone has tried it in a real client. Some problems only show up there — for example, whether the client supports a given MCP feature.
Flow of a change:
The change is developed on its own branch, usually one per issue, and proposed with a pull request.
The automated tests run on every pull request (the Tests workflow, .github/workflows/tests.yml, on Python 3.11–3.13) and must pass before merging. Integration tests need a real OAuth token and are run by hand (see tests/README.md).
The pull request is merged into main with rebase: merge commits are disabled on this repository, and rebase keeps each commit of the branch on main. The tests run again on main, and if they pass latest moves to the new commit.
If it works, latest is promoted to stable. If a bug turns up, stable stays where it is, and the fix goes through the same flow.
Promoting to stable: on GitHub, Actions → Release tags → Run workflow. Leave "Commit" empty to promote the commit latest points to, or enter the SHA of an earlier commit on main (e.g. to roll stable back). Commits that are not on main are refused. The workflow is in .github/workflows/release-tags.yml.
A green Tests run is required before merging only if it is set as a required status check in the branch protection of main (Settings → Branches); otherwise the rule relies on whoever merges.