Google Chat MCP Server

How to use

You can operate this MCP server with either a command-line driven mode or a web-based authentication flow. The server exposes tools to list Google Chat spaces and to fetch messages from a specific space within a date range.

To start authentication in CLI mode (recommended for headless or remote environments): run the following in your shell. This will prompt you to authorize access on a device you control and save the resulting token locally.

uv run python server.py --auth cli

In environments with a local browser, you can use web authentication. The server runs a web interface on port 8000 where you complete Google login, and the token is saved for future use.

uv run python server.py --auth web --port 8000

Once authenticated, you can use the MCP client to interact with the Google Chat integration. The configuration for MCP client usage typically involves referencing the server and providing the token path so the client can communicate with the server.

How to install

Prerequisites you need before installation: Python 3.13 or newer, a Google Cloud project with the Google Chat API and People API enabled, and OAuth2 credentials from Google Cloud Console. Prepare a credentials.json file at the top level of your project to enable OAuth2 client authentication.

Step-by-step setup flow you can follow to get the MCP server running:

git clone https://github.com/chy168/google-chat-mcp-server.git
cd google-chat-mcp-server

Create and configure a Google Cloud OAuth2 Web client. In the Google Cloud Console, create a Web application OAuth 2.0 client and download the credentials as credentials.json. Place credentials.json at the project root.

Authenticate to obtain and refresh tokens. You can use either CLI mode or Web mode as described in the usage section. The token will be stored locally as token.json and used by the MCP server to access Google Chat data.

Configure the MCP client to run the server with the token path you saved.

Start the MCP server or the authenticated tools as shown in the usage section, ensuring the token-path points to token.json.

Configuration and usage notes

MCP configuration can reference the server to run the Google Chat tools. The following example shows how you would configure an MCP client to run the server with a token path.

{
  "mcpServers": {
    "google_chat": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_REPO_PATH>/google-chat-mcp-server",
        "run",
        "server.py",
        "--token-path",
        "<YOUR_REPO_PATH>/google-chat-mcp-server/token.json"
      ]
    }
  }
}

Docker / container usage

You can run the integration in containers. Use the official container image and mount your project directory containing token.json to provide the token to the container.

docker run -it --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --token-path=/data/token.json

If you prefer Podman, the equivalent command is:

podman run -it --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --token-path=/data/token.json

Run the authentication server in containers

The authentication server handles Google account authentication and can run in web mode or CLI mode inside a container.

# Web mode
docker run -it --rm \
  -p 8000:8000 \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --auth web --host 0.0.0.0 --port 8000 --token-path=/data/token.json

CLI mode for headless environments:

docker run -t --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --auth cli --token-path=/data/token.json

Tools

The MCP server provides tools to interact with Google Chat data.

get_chat_spaces: List all Google Chat spaces the bot has access to.

get_space_messages(space_name: str, start_date: str, end_date: str = None): List messages from a specific Google Chat space with optional date filtering.

Development and debugging

Build the container image locally to customize or test changes.

docker build -t google-chat-mcp-server:latest .
# or
podman build -t google-chat-mcp-server:latest .

For active development, you can run a fast, editable server session using the following command to start a development server with editable mode.

fastmcp dev server.py --with-editable .

get_chat_spaces

Lists all Google Chat spaces the bot has access to.

get_space_messages

Retrieves messages from a specific Google Chat space with optional date filtering.