# Google Meet & Calendar MCP Server

<!-- mcp-name: io.github.workos/gmeet-mcp-server -->

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Google Meet and Google Calendar. Connect any AI agent to Google Calendar & Meet — create meetings with Meet links, manage events, browse calendars, access recordings, transcripts, and participant data.

**This is an independent, generalized MCP server.** It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

## Features

- 📅 **Calendar Events**: Create, read, update, delete, and list events
- 🎥 **Meetings**: Create Google Meet meetings with auto-generated links
- 👥 **Attendees**: Add attendees to events
- 📋 **Calendars**: List all accessible calendars
- 🎬 **Recordings**: List and download meeting recordings (Meet REST API v2)
- 📝 **Transcripts**: Access meeting transcripts (Meet REST API v2)
- 👤 **Participants**: View meeting participant history (Meet REST API v2)
- 📊 **Conference Records**: Browse past meeting records

## Installation

**Recommended — no pre-install required (uses [uv](https://docs.astral.sh/uv/)):**
```bash
# uv manages a temporary isolated environment automatically
uvx --from workos-gmeet-mcp-server gmeet-mcp-server
```

**Or install permanently with pip:**
```bash
pip install workos-gmeet-mcp-server
```

**Or install from source:**
```bash
git clone https://github.com/workos/workos-gmeet-mcp-server
cd workos-gmeet-mcp-server
pip install -e .
```

## Quick Start

```bash
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="GOCSPX-your-secret"
export GOOGLE_REFRESH_TOKEN="1//your-refresh-token"

# Recommended: run via uvx (no install needed)
uvx --from workos-gmeet-mcp-server gmeet-mcp-server

# Or if installed via pip
gmeet-mcp-server

# Or run as a Python module
python -m gmeet_mcp_server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GOOGLE_CLIENT_ID` | ✅ Yes | OAuth2 Client ID from Google Cloud Console |
| `GOOGLE_CLIENT_SECRET` | ✅ Yes | OAuth2 Client Secret |
| `GOOGLE_REFRESH_TOKEN` | ✅ Yes | OAuth2 Refresh Token (generated once, used to auto-refresh access tokens) |

### Getting Google OAuth2 Credentials

#### 1. Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select existing)
3. Enable these APIs under APIs & Services → Library:
   - **Google Calendar API**
   - **Google Meet REST API** (for recordings/transcripts)
   - **Google Drive API** (for downloading recordings)

#### 2. Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose **External** user type
3. Fill in app name and email
4. Add scopes:
   - `https://www.googleapis.com/auth/calendar`
   - `https://www.googleapis.com/auth/meetings.space.readonly`
   - `https://www.googleapis.com/auth/drive.readonly`

#### 3. Create OAuth2 Credentials

1. Go to APIs & Services → Credentials
2. Click **Create Credentials** → **OAuth client ID**
3. Application type: **Desktop app**
4. Note down the **Client ID** and **Client Secret**

#### 4. Generate a Refresh Token

**Option A — Using Google OAuth Playground:**
1. Go to [OAuth 2.0 Playground](https://developers.google.com/oauthplayground)
2. Click ⚙️ Settings → check **Use your own OAuth credentials** → enter your Client ID & Secret
3. In Step 1, add scopes:
   - `https://www.googleapis.com/auth/calendar`
   - `https://www.googleapis.com/auth/meetings.space.readonly`
   - `https://www.googleapis.com/auth/drive.readonly`
4. Click **Authorize APIs** → sign in → grant access
5. In Step 2, click **Exchange authorization code for tokens**
6. Copy the **Refresh Token**

**Option B — Using the included helper script:**
```bash
python MCP_servers/get_google_token.py \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET"
```

## Connecting to AI Agents

> **Note:** Use `uvx --from workos-gmeet-mcp-server gmeet-mcp-server` in all configs below. The `--from` flag is needed because the PyPI package name (`workos-gmeet-mcp-server`) differs from the CLI entry point (`gmeet-mcp-server`). You must have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (`brew install uv` on macOS).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gmeet": {
      "command": "uvx",
      "args": ["--from", "workos-gmeet-mcp-server", "gmeet-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-secret",
        "GOOGLE_REFRESH_TOKEN": "1//your-refresh-token"
      }
    }
  }
}
```

> **Alternative** — if you have installed via `pip install workos-gmeet-mcp-server` and prefer not to use uvx, use the full absolute path to the binary instead:
> ```json
> { "command": "/path/to/your/bin/gmeet-mcp-server" }
> ```
> Find the path with: `which gmeet-mcp-server`

### Cursor

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "gmeet": {
      "command": "uvx",
      "args": ["--from", "workos-gmeet-mcp-server", "gmeet-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-secret",
        "GOOGLE_REFRESH_TOKEN": "1//your-refresh-token"
      }
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Edit `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "gmeet": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-gmeet-mcp-server", "gmeet-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "${input:googleClientId}",
        "GOOGLE_CLIENT_SECRET": "${input:googleClientSecret}",
        "GOOGLE_REFRESH_TOKEN": "${input:googleRefreshToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "googleClientId",
      "type": "promptString",
      "description": "Google OAuth2 Client ID"
    },
    {
      "id": "googleClientSecret",
      "type": "promptString",
      "description": "Google OAuth2 Client Secret",
      "password": true
    },
    {
      "id": "googleRefreshToken",
      "type": "promptString",
      "description": "Google OAuth2 Refresh Token",
      "password": true
    }
  ]
}
```

### WorkOS / Custom Agents

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "gmeet": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-gmeet-mcp-server", "gmeet-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
        "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
      }
    }
  }
}
```

## Available Tools (14)

### Calendar Events

| Tool | Description |
|------|-------------|
| `gmeet_list_events` | List upcoming calendar events |
| `gmeet_create_event` | Create a calendar event (no Meet link) |
| `gmeet_get_event` | Get details of a specific event |
| `gmeet_update_event` | Update an existing event |
| `gmeet_delete_event` | Delete a calendar event |

### Meetings

| Tool | Description |
|------|-------------|
| `gmeet_create_meeting` | Create a calendar event WITH a Google Meet link |
| `gmeet_add_attendee` | Add an attendee to an existing event |

### Calendars

| Tool | Description |
|------|-------------|
| `gmeet_list_calendars` | List all accessible calendars |

### Recordings & Transcripts (Meet REST API v2)

| Tool | Description |
|------|-------------|
| `gmeet_list_conference_records` | Browse past meeting records |
| `gmeet_get_meeting_participants` | View participant history for a meeting |
| `gmeet_list_recordings` | List recordings for a meeting |
| `gmeet_list_transcripts` | List transcripts for a meeting |
| `gmeet_download_recording` | Download a meeting recording via Google Drive |
| `gmeet_get_transcript_content` | Get transcript text content via Google Docs |

## Development

```bash
git clone https://github.com/workos/workos-gmeet-mcp-server
cd workos-gmeet-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_REFRESH_TOKEN=... python -m gmeet_mcp_server
```

## Publishing

### To PyPI
```bash
pip install build twine
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*
```

### To MCP Registry
```bash
mcp-publisher login github
mcp-publisher publish
```

## License

MIT — see [LICENSE](LICENSE) for details.
