gchat-mcp

MCP (Model Context Protocol) server for Google Chat integration. This server provides tools to interact with Google Chat spaces and messages.

Features

• List all Google Chat spaces you're a member of
• Retrieve recent messages from any space
• Search messages by text content

Installation

Using uv

# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e ".[dev]"

Or with pip

pip install -e ".[dev]"

Setup

1. Create a Google Cloud project: https://console.cloud.google.com/

2. Enable Google Chat API:

   gcloud services enable chat.googleapis.com
   

3. Create a service account:

   • Go to IAM & Admin > Service Accounts
   • Click "Create Service Account"
   • Give it a name (e.g., "gchat-mcp")
   • Click "Generate Key" and select JSON format
   • Download the JSON file

4. Place credentials: Put your service account JSON as credentials.json in the project root

5. Validate credentials:

   make oauth
   # or
   uv run python oauth_setup.py credentials.json
   

Usage

As an MCP Server

# Start the MCP server
uv run python -m src.apps.gchat_mcp.server

Available Tools

list_spaces()

Returns a list of Google Chat spaces the authenticated user is a member of.

Example:

from src.apps.gchat_mcp.server import app

# In MCP context
spaces = await app.call_tool("list_spaces")
print(spaces)
# [{'spaceId': 'abc123', 'name': 'General', 'iconLink': 'https://...'}]

list_messages(space_id, limit=20)

Retrieves recent messages from a specific space.

Arguments:

• space_id (str): The unique identifier of the space
• limit (int, optional): Maximum number of messages to retrieve (default: 20)

Example:

messages = await app.call_tool("list_messages", {"space_id": "abc123", "limit": 10})
print(messages)
# [{'messageId': 'msg1', 'text': 'Hello!', 'authorName': 'User1', ...}]

search_messages(space_id, query)

Searches for messages containing specific text in a space.

Arguments:

• space_id (str): The unique identifier of the space to search in
• query (str): The text query to search for

Example:

results = await app.call_tool("search_messages", {"space_id": "abc123", "query": "meeting"})
print(results)
# [{'messageId': 'msg1', 'text': 'Meeting at 3pm...', 'authorName': 'User1', ...}]

Project Structure

ai-meetup-demo/
├── pyproject.toml
├── README.md
├── src/
│   ├── config/           # Configuration files
│   │   └── __init__.py
│   ├── apps/
│   │   └── gchat_mcp/    # MCP server application
│   │       ├── __init__.py
│   │       └── server.py
│   └── manage.py         # Entry point
├── credentials.json      # Google Cloud service account (add to .gitignore)
├── oauth_setup.py        # OAuth setup helper script
├── examples/
│   └── example_usage.py  # Usage examples
└── tests/
    └── test_server.py    # Unit tests

Configuration

Service Account

Place your Google Cloud service account JSON as credentials.json in the project root. This file is excluded from git.

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Check code quality
uv run ruff check src/
uv run ruff format src/ --check

License

MIT