Google Workspace MCP

A unified MCP server for Google Workspace APIs: Chat, Gmail, and Calendar.

Installation

npm install

Related MCP server: google-workspace-mcp

Setup

The MCP handles authentication automatically via OpenCode:

1. First Run: When OpenCode starts the MCP, it passes GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET via environment variables

2. OAuth Flow: On first run, the server checks for tokens in ~/.local/share/opencode/mcp-auth.json

3. If No Tokens: Server initiates OAuth flow (browser login)

4. Subsequent Runs: Tokens are loaded automatically

No manual setup needed when running via OpenCode.

Manual Setup (if needed)

For testing outside OpenCode, set environment variables and run the server:

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-secret-here"
node server.js

The server will detect missing tokens and initiate OAuth flow automatically.

Usage

The MCP provides 16 tools across 3 services:

Chat (4 tools)

• chat_search_conversations — Search/list Google Chat spaces

• chat_list_messages — Retrieve messages from a space or thread

• chat_search_messages — Search messages by keywords, sender, time

• chat_send_message — Send message to space or reply to thread

Gmail (6 tools)

• gmail_list_messages — List emails with optional query

• gmail_get_message — Retrieve full message details

• gmail_search_messages — Search emails with Gmail syntax

• gmail_send_message — Send new email

• gmail_list_labels — List all labels and counts

• gmail_modify_message — Add/remove labels from message

Calendar (6 tools)

• calendar_list_events — List events in time range

• calendar_get_event — Retrieve event details

• calendar_create_event — Create new calendar event

• calendar_update_event — Modify existing event

• calendar_delete_event — Delete calendar event

• calendar_find_free_slots — Find available time slots

Testing

npm run test

Tests require tokens to exist. Run npm run setup first if you haven't authenticated.

Configuration

The MCP is configured in opencode.jsonc:

{
  "mcp": {
    "google-workspace": {
      "type": "local",
      "command": ["node", "D:\\OneDrive\\Workspace\\google-workspace-mcp\\server.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id-here.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-secret-here"
      },
      "enabled": true
    }
  }
}

Both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set for OAuth to work.

Architecture

• server.js — MCP dispatcher with all 16 tools (receives env from OpenCode)

• services/ — Modular service implementations (Chat, Gmail, Calendar)

• utils/ — Shared OAuth token management and HTTP client

Token Refresh

Tokens are automatically refreshed when:

• Access token expires (< 60 seconds remaining)

• A tool request is made

Refresh logic is transparent — no manual intervention needed.

See AGENTS.md for repository conventions, contribution guidance, and security notes.