Google Workspace MCP Server

MCP server providing Google Drive, Sheets, Gmail, Calendar, and Tasks access via OAuth authentication. Designed for use with Ignitive Furnace v2 control plane.

Version

1.0.0 — File-based OAuth tokens only. Simplified architecture for control plane integration.

Architecture

Furnace Control Plane
  ↓ (OAuth callback writes tokens)
/workspace/{clientId}/{agentId}/google-tokens.json
  ↓ (mounted into agent container)
Google Workspace MCP Server
  ↓ (makes API calls)
Google Workspace APIs

How It Works

1. User authenticates — Control plane OAuth callback writes tokens to fixed file path
2. Agent container starts — MCP reads GOOGLE_TOKEN_PATH env var
3. MCP reads tokens — Loads from file on first API call
4. MCP refreshes tokens — Uses google-auth-library with 60-second proactive buffer
5. MCP writes tokens — Updated tokens (including rotated refresh_token) written back to same file
6. No database sync — File is single source of truth

Token refresh uses Google's OAuth2Client with automatic persistence via event listener.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_CLIENT_ID | Yes | OAuth client ID from GCP Console | | GOOGLE_CLIENT_SECRET | Yes | OAuth client secret from GCP Console | | GOOGLE_TOKEN_PATH | Yes | Path to google-tokens.json file (e.g., /workspace/{clientId}/{agentId}/google-tokens.json) | | GOOGLE_ROOT_FOLDER_ID | No | Google Drive folder ID that scopes Drive operations | | GOOGLE_SERVICES | No | Comma-separated enabled services (default: drive,sheets,gmail,calendar,tasks) | | GOOGLE_READONLY | No | If true, only read tools for Drive/Sheets (default: false) |

Token File Format

The control plane writes this file after OAuth callback:

{
  "access_token": "",
  "refresh_token": "1//0abc...",
  "expires_at": 0,
  "scope": "https://www.googleapis.com/auth/drive ..."
}

• access_token can be empty (MCP refreshes immediately)
• expires_at can be 0 (triggers immediate refresh)
• refresh_token is the long-lived token
• scope contains all granted OAuth scopes

The MCP updates this file automatically when tokens refresh.

Tools (52 total)

Drive (16 tools)

| Tool | R/W | Description | |------|-----|-------------| | drive_list_files | R | List files in folder (paginated) | | drive_list_folders | R | List only folders in folder | | drive_get_file | R | Get file metadata | | drive_read_file | R | Read text file content (truncates at 1MB) | | drive_download | R | Get download URL for binary files | | drive_search | R | Search files by name in root tree | | drive_tree | R | Get folder tree structure | | drive_create_folder | W | Create folder | | drive_create_file | W | Create text file | | drive_update_file | W | Update file content | | drive_move_file | W | Move file to different folder | | drive_rename_file | W | Rename file/folder | | drive_delete_file | W | Trash file/folder | | drive_share_file | W | Set link sharing (private/anyone/anyone_with_link) | | drive_add_collaborator | W | Add user as collaborator | | drive_remove_collaborator | W | Remove collaborator | | drive_get_permissions | R | Get file permissions and collaborators |

Sheets (13 tools)

| Tool | R/W | Description | |------|-----|-------------| | sheets_list | R | List all spreadsheets in root folder | | sheets_get_info | R | Get spreadsheet metadata and sheets | | sheets_get_sheet | R | Get specific sheet/tab metadata | | sheets_read_cell | R | Read single cell | | sheets_read_range | R | Read range (truncates at 10k rows) | | sheets_read_all | R | Read entire sheet | | sheets_write_cell | W | Write single cell | | sheets_write_range | W | Write 2D array to range | | sheets_append_row | W | Append row to end of sheet | | sheets_clear_range | W | Clear range values | | sheets_create_sheet | W | Create new sheet/tab | | sheets_delete_sheet | W | Delete sheet/tab | | sheets_create_spreadsheet | W | Create new spreadsheet file |

Gmail (8 tools)

| Tool | R/W | Description | |------|-----|-------------| | gmail_search_messages | R | Search messages with query | | gmail_read_message | R | Get full message with decoded body and attachment metadata | | gmail_read_thread | R | Get all messages in thread with attachment metadata | | gmail_send_message | W | Send email (HTML or plain text, optional attachments) | | gmail_create_draft | W | Create email draft (optional attachments) | | gmail_modify_labels | W | Add/remove labels on message | | gmail_list_labels | R | List all labels | | gmail_get_attachment | R | Download attachment content by messageId and attachmentId |

Calendar (8 tools)

| Tool | R/W | Description | |------|-----|-------------| | gcal_list_calendars | R | List all calendars | | gcal_list_events | R | List events in calendar | | gcal_get_event | R | Get single event details | | gcal_create_event | W | Create new event | | gcal_update_event | W | Update existing event | | gcal_delete_event | W | Delete event | | gcal_respond_to_event | W | Accept/decline/tentative response |

Tasks (8 tools)

| Tool | R/W | Description | |------|-----|-------------| | gtasks_list_tasklists | R | List all task lists | | gtasks_get_tasklist | R | Get a specific task list | | gtasks_list_tasks | R | List tasks in a task list | | gtasks_get_task | R | Get a specific task | | gtasks_create_task | W | Create a new task | | gtasks_update_task | W | Update task (title, notes, status, due date) | | gtasks_delete_task | W | Delete a task | | gtasks_clear_tasks | W | Clear all completed tasks from a list |

Service Filtering

Only register tools the agent needs — saves context tokens:

"GOOGLE_SERVICES": "sheets"               // Only Sheets tools
"GOOGLE_SERVICES": "drive,sheets"         // Drive + Sheets
"GOOGLE_SERVICES": "drive,sheets,gmail"   // Drive + Sheets + Gmail

OAuth Scopes

| Service | Scope URLs | |---------|-----------| | Drive | https://www.googleapis.com/auth/drive | | Sheets | https://www.googleapis.com/auth/spreadsheets | | Gmail | https://www.googleapis.com/auth/gmail.compose, https://www.googleapis.com/auth/gmail.modify | | Calendar | https://www.googleapis.com/auth/calendar | | Tasks | https://www.googleapis.com/auth/tasks |

Installation

npx -y @ignitive/google-workspace-mcp

Development

npm install
npm run build      # Compile TypeScript
npm run dev        # Run with tsx
npm run typecheck  # Type check only

Publishing

npm run build
npm publish --access public

License

MIT