Google Workspace MCP Server

MCP server for Google Slides, Sheets, Docs, and Drive. Enables AI assistants to create, read, and modify Google Workspace documents programmatically.

Quick Start

npm install
npm run build
npm run get-token  # One-time OAuth setup
npm start

Configuration

Required Environment Variables

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token

Optional Module Toggles

All modules enabled by default. Set to false to disable:

ENABLE_SHEETS=false
ENABLE_SLIDES=false
ENABLE_DOCS=false
ENABLE_REVISIONS=false

Drive tools are always enabled (core functionality).

Claude Code Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "node",
      "args": ["/path/to/google-workspace-mcp/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Available Tools

Drive (always enabled)

| Tool | Description | |------|-------------| | create_folder | Create a folder in Google Drive | | list_files | List files/folders with filtering, pagination, and sorting. Supports Shared Drives. | | get_file | Get detailed metadata for a specific file (permissions, capabilities, owners) | | search_files | Search Drive using query syntax (e.g., name contains 'report') | | export_file | Export Google Docs/Sheets/Slides to PDF, text, CSV, docx, etc. |

Sheets

| Tool | Description | |------|-------------| | create_spreadsheet | Create a new spreadsheet | | get_spreadsheet | Get spreadsheet metadata | | get_sheet_values | Read cell values | | update_sheet_values | Write cell values | | batch_update_spreadsheet | Apply formatting/structural changes | | append_sheet_values | Append rows | | summarize_spreadsheet | Extract all data | | copy_sheet | Copy sheet between spreadsheets |

Slides

| Tool | Description | |------|-------------| | create_presentation | Create a new presentation | | get_presentation | Get presentation metadata | | batch_update_presentation | Apply updates to slides | | get_page | Get specific slide details | | summarize_presentation | Extract text from all slides |

Docs

| Tool | Description | |------|-------------| | create_document | Create a new document | | get_document | Get document content | | batch_update_document | Insert/delete/format text | | summarize_document | Extract text content |

Version History

| Tool | Description | |------|-------------| | list_revisions | List document version history | | get_revision | Get revision details with restore instructions |

Security

OAuth Scopes

This server requests the minimum scopes needed:

| Scope | Purpose | |-------|---------| | presentations | Create/edit Google Slides | | spreadsheets | Create/edit Google Sheets | | documents | Create/edit Google Docs | | drive.readonly | Browse, search, and read file metadata (including Shared Drives) | | drive.file | Export and manage files created by this app |

What This Server CAN Access

• All Slides presentations in your account
• All Sheets spreadsheets in your account
• All Docs documents in your account
• Drive file metadata, browsing, and search (including Shared Drives)
• Export Google Workspace files to other formats (PDF, text, CSV, etc.)

What This Server CANNOT Access

• Gmail, Calendar, or other Google services
• Delete or permanently modify files you don't own
• Your Google account password or 2FA settings

Security Best Practices

1. Never commit .env files to version control
2. Use a dedicated Google Cloud project for this server
3. Review access at Google Account Permissions
4. Regenerate tokens with npm run get-token if compromised

OAuth Setup

1. Enable APIs

In Google Cloud Console:

1. Create or select a project
2. Enable: Slides API, Sheets API, Docs API, Drive API

2. Create Credentials

1. Go to APIs & Services > Credentials
2. Create OAuth client ID (Desktop app type)
3. Download client ID and secret

3. Configure Consent Screen

Add these scopes:

• https://www.googleapis.com/auth/presentations
• https://www.googleapis.com/auth/spreadsheets
• https://www.googleapis.com/auth/documents
• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive.file

4. Generate Refresh Token

# Add client ID and secret to .env first
npm run get-token

The refresh token is generated once and stored. Regenerate only if:

• You change OAuth scopes
• You revoke access from your Google account
• You need to use a different account

Troubleshooting

"Request had insufficient authentication scopes"

1. Verify all 5 scopes are in your OAuth consent screen
2. Regenerate token: npm run get-token
3. Restart the MCP server

"API has not been used in project"

Enable the missing API in Google Cloud Console. The error message includes a direct link.

One service works but another doesn't

The token was generated without all scopes. Add missing scopes to consent screen and regenerate with npm run get-token.

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run lint         # Run ESLint
npm test             # Run tests
npm run get-token    # Generate OAuth token

Testing with MCP Inspector

export $(cat .env | xargs) && npx @modelcontextprotocol/inspector node build/index.js

License

ISC