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

$3

``bash
npm install mcp-server-google-workspace


or


pnpm add mcp-server-google-workspace
`

$3

`bash
git clone
cd mcp-server-google-workspace
pnpm install
pnpm build
`

Authentication

The MCP server reads Google OAuth credentials from environment variables:

`bash


.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
`

$3

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

$3

#### 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:
`json
{
"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"

$3

#### 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:
`json
{
"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):
`json
{
"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:
`json
{
"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)

$3

#### 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:
`json
{
"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:
`json
{
"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:
`json
{
"fileId": "1ABC123xyz",
"role": "reader",
"type": "user",
"emailAddress": "colleague@example.com",
"emailMessage": "Please review this document"
}
`

Usage

$3

Add to your Claude Desktop configuration:

`json
{
"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"
}
}
}
}
`

$3

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

`typescript
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

`bash


Install dependencies

pnpm install

Build

pnpm build

Watch mode

pnpm watch

Run locally

pnpm dev
`

Testing

$3

`bash
npx @modelcontextprotocol/inspector node dist/index.js
`

$3

`bash
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