MCP Server - Google Workspace

A Model Context Protocol (MCP) server for Google Workspace integration, providing tools for Gmail, Google Calendar, and Google Drive access.

Features

• 🔐 Simple Authentication: Environment variable based credentials
• 📧 Gmail: List, read, search, and send emails
• 📅 Calendar: List calendars (including shared), list and create events in any accessible calendar
• 🌍 UTC Standardization: All calendar event times are automatically converted to UTC for consistent processing
• 📁 Drive: Full file management - list, read, upload, update, move, delete, search files; create folders; manage sharing
• 🔄 Auto Token Refresh: Automatic OAuth token refresh
• 🏢 Multi-User Support: Host applications can decrypt and inject user-specific credentials
• 🤝 Shared Calendar Support: Access and manage events in calendars shared with you

Installation

For Individual Use

npm install mcp-server-google-workspace
# or
pnpm add mcp-server-google-workspace

For Development

git clone <repo-url>
cd mcp-server-google-workspace
pnpm install
pnpm build

Authentication

The MCP server reads Google OAuth credentials from environment variables:

# .env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token
GOOGLE_ACCESS_TOKEN=your_access_token  # optional

Multi-User Platforms

For platforms serving multiple users, the host application should:

1. Fetch encrypted credentials from database
2. Decrypt credentials (e.g., using AWS KMS)
3. Pass decrypted credentials as environment variables when starting the MCP server

This keeps the MCP server simple and delegates credential management to the host application.

Available Tools

Gmail Tools

gmail_list_emails

List recent emails from Gmail inbox.

Parameters:

• hours (number, optional): Hours to look back (default: 24)
• maxResults (number, optional): Max emails to return (default: 50)
• query (string, optional): Gmail search query

Example:

{
  "hours": 168,
  "maxResults": 50,
  "query": "from:boss@company.com"
}

gmail_read_email

Read full content of a specific email.

Parameters:

• emailId (string, required): Gmail message ID

gmail_search_emails

Search emails with Gmail query syntax.

Parameters:

• query (string, required): Search query
• maxResults (number, optional): Max results (default: 50)

Query Examples:

• "from:user@example.com subject:meeting"
• "has:attachment after:2025/11/01"
• "is:unread label:important"

Calendar Tools

calendar_list_calendars

List all accessible calendars, including shared calendars.

Parameters:

• showHidden (boolean, optional): Include hidden calendars (default: false)
• minAccessRole (string, optional): Minimum access role filter (freeBusyReader, reader, writer, owner)

Example:

{
  "showHidden": false,
  "minAccessRole": "reader"
}

Response: Returns a list of calendars with their IDs, names, access roles, and other metadata. Use the calendar id field for other calendar operations.

calendar_list_events

List calendar events for a date range. All event times are returned in UTC.

Parameters:

• calendarId (string, optional): Calendar ID (default: 'primary'). Use calendar_list_calendars to get IDs of shared calendars.
• date (string, optional): Start date (YYYY-MM-DD), default: today
• days (number, optional): Number of days (default: 1)
• maxResults (number, optional): Max events (default: 50)

Response: All event times (start and end) are automatically converted to UTC GMT format (e.g., "Sat, 02 Nov 2025 11:00:00 GMT"), regardless of the calendar's original timezone. This makes it easy to compare and process events across different timezones.

calendar_create_event

Create a new calendar event with timezone support. Returns event times in UTC.

Parameters:

• calendarId (string, optional): Calendar ID (default: 'primary'). Use calendar_list_calendars to get IDs of shared calendars.
• summary (string, required): Event title
• start (string, required): Start time (ISO 8601). Use with timeZone to specify local time.
• end (string, required): End time (ISO 8601). Use with timeZone to specify local time.
• timeZone (string, optional): IANA timezone (e.g., "America/New_York", "Europe/Istanbul", "UTC"). The start/end times will be interpreted in this timezone. If not specified, uses the calendar's default timezone.
• description (string, optional): Event description
• location (string, optional): Event location
• attendees (array, optional): Attendee emails

Examples:

Creating event at 14:00 Istanbul time (GMT+3):

{
  "summary": "Team Meeting",
  "start": "2025-11-02T14:00:00",
  "end": "2025-11-02T15:00:00",
  "timeZone": "Europe/Istanbul"
}

Response will have: "start": "Sat, 02 Nov 2025 11:00:00 GMT" (converted to UTC)

Creating event at 10:00 EST:

{
  "summary": "Team Meeting",
  "start": "2025-11-02T10:00:00",
  "end": "2025-11-02T11:00:00",
  "timeZone": "America/New_York"
}

Response will have: "start": "Sat, 02 Nov 2025 15:00:00 GMT" (converted to UTC)

Drive Tools

drive_list_files

List files and folders from Google Drive.

Parameters:

• folderId (string, optional): Parent folder ID (default: root)
• pageSize (number, optional): Number of files to return (default: 50, max: 1000)
• pageToken (string, optional): Token for pagination
• query (string, optional): Drive query string (e.g., "name contains 'report'")
• orderBy (string, optional): Sort order (default: "modifiedTime desc")
• includeItemsFromAllDrives (boolean, optional): Include shared drives (default: false)
• includeTrashed (boolean, optional): Include trashed items (default: false)

Example:

{
  "folderId": "0B1234567890",
  "pageSize": 100,
  "query": "mimeType='application/pdf'"
}

drive_read_file

Read file content from Google Drive. Automatically detects file type and returns appropriate encoding.

Parameters:

• fileId (string, required): File ID to read
• exportMimeType (string, optional): For Google Workspace files, export format (e.g., "application/pdf")

Response:

• Text files: Returned as UTF-8 strings
• Binary files: Returned as base64-encoded strings
• Google Workspace files: Automatically exported to common formats (Docs→PDF, Sheets→XLSX)
• Large files: 10MB size limit; larger files return metadata with download link

Example:

{
  "fileId": "1ABC123xyz",
  "exportMimeType": "application/pdf"
}

drive_search_files

Search files using Google Drive query syntax.

Parameters:

• query (string, required): Drive query (e.g., "name contains 'report' and mimeType='application/pdf'")
• pageSize (number, optional): Max results (default: 50)
• pageToken (string, optional): Pagination token
• orderBy (string, optional): Sort order
• includeItemsFromAllDrives (boolean, optional): Include shared drives

Query Examples:

• "name contains 'budget' and mimeType='application/pdf'"
• "modifiedTime > '2025-01-01T00:00:00'"
• "'me' in owners and starred=true"
• "fullText contains 'important'"

drive_create_folder

Create a new folder in Google Drive.

Parameters:

• name (string, required): Folder name
• parentId (string, optional): Parent folder ID (default: root)
• description (string, optional): Folder description

drive_upload_file

Upload a new file to Google Drive.

Parameters:

• name (string, required): File name
• content (string, required): File content (base64 for binary, UTF-8 for text)
• mimeType (string, required): MIME type (e.g., "text/plain", "application/pdf")
• encoding (string, optional): Content encoding (base64 or utf-8, default: utf-8)
• parentId (string, optional): Parent folder ID
• description (string, optional): File description

drive_update_file

Update an existing file's content and/or metadata.

Parameters:

• fileId (string, required): File ID to update
• name (string, optional): New file name
• content (string, optional): New file content
• mimeType (string, optional): New MIME type
• encoding (string, optional): Content encoding
• description (string, optional): New description

drive_move_file

Move a file to a different folder.

Parameters:

• fileId (string, required): File ID to move
• newParentId (string, required): New parent folder ID
• removeParents (array, optional): Parent IDs to remove

drive_delete_file

Delete a file (trash or permanent).

Parameters:

• fileId (string, required): File ID to delete
• permanent (boolean, optional): If true, permanently delete; if false, move to trash (default: false)

drive_get_file

Get detailed metadata for a file.

Parameters:

• fileId (string, required): File ID
• includePermissions (boolean, optional): Include permissions info (default: false)

drive_share_file

Share a file by creating a permission.

Parameters:

• fileId (string, required): File ID to share
• role (string, required): Permission role (reader, commenter, writer)
• type (string, required): Permission type (user, group, domain, anyone)
• emailAddress (string, optional): Email address (required for user/group type)
• domain (string, optional): Domain name (required for domain type)
• sendNotificationEmail (boolean, optional): Send notification email (default: true)
• emailMessage (string, optional): Custom message in notification

Example:

{
  "fileId": "1ABC123xyz",
  "role": "reader",
  "type": "user",
  "emailAddress": "colleague@example.com",
  "emailMessage": "Please review this document"
}

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-workspace"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Programmatic Usage (e.g., with Claude Agent SDK)

For multi-user platforms, decrypt credentials and inject them when starting the server:

import { Agent } from '@anthropic-ai/claude-agent-sdk';

// Your backend decrypts credentials from database
const credentials = await decryptUserCredentials(userId);

const agent = new Agent({
  mcpServers: [{
    command: 'node',
    args: ['path/to/mcp-server-google-workspace/dist/index.js'],
    env: {
      GOOGLE_CLIENT_ID: credentials.clientId,
      GOOGLE_CLIENT_SECRET: credentials.clientSecret,
      GOOGLE_REFRESH_TOKEN: credentials.refreshToken,
    }
  }]
});

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm watch

# Run locally
pnpm dev

Testing

With MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

With Environment Variables

cp .env.example .env
# Edit .env with your credentials
pnpm dev

OAuth Setup

To get Google OAuth credentials:

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Gmail API, Google Calendar API, and Google Drive API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI
6. Get client ID and client secret
7. Use OAuth playground to get refresh token with required scopes:
   • https://www.googleapis.com/auth/gmail.readonly (for Gmail read)
   • https://www.googleapis.com/auth/gmail.send (for Gmail send)
   • https://www.googleapis.com/auth/calendar (for Calendar)
   • https://www.googleapis.com/auth/drive (for Drive full access)
   • Or use more restrictive scopes like drive.readonly or drive.file as needed

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

MIT

Author

iskifogl