Google Workspace Service Account MCP Server

MCP server providing Google Drive, Sheets, Gmail, Calendar, and Tasks access via service account authentication with domain-wide delegation. Designed for Google Workspace business clients.

Version

4.0.0 — Service account-only server. Split from original dual-mode server. Removed OAuth authentication.

Architecture

flowchart TB
    subgraph Container["Agent Container"]
        MCP["MCP Server (this package)"]
        JWT["google-auth-library<br/>JWT Client"]
        APIs["googleapis<br/>(Drive/Sheets/Gmail/Calendar/Tasks)"]

        MCP --> JWT
        MCP --> APIs
        APIs -->|"API calls (impersonating user)"| Google["Google Workspace APIs"]
        MCP -->|"scope check (once)"| TokenInfo["Google Tokeninfo API"]
    end

    SA["Service Account JSON<br/>(key file)"] -->|"key file"| JWT

    style Container fill:#f3e5f5
    style Google fill:#e8f5e9
    style TokenInfo fill:#fff9c4

How It Works

1. Agent calls MCP tool (e.g., drive_list_files)
2. First call only — MCP reads service account key, creates JWT client with subject impersonation, authorizes, and verifies granted scopes via Google's tokeninfo endpoint
3. Subsequent calls — reuses initialized client (no refresh needed, JWT tokens are self-signed)
4. If scopes are missing — returns clear error naming missing scopes and service account email (admin needs to update delegation)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_SERVICE_ACCOUNT_PATH | Yes | Path to service account JSON key file | | GOOGLE_IMPERSONATE_USER | Yes | Email address to impersonate (domain-wide delegation) | | 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) |

Scope Verification

On first tool call, the MCP verifies the Workspace admin has granted the required scopes via domain-wide delegation:

Error: Service account ([email protected]) is missing delegated scopes:
https://www.googleapis.com/auth/gmail.compose. Ask your Workspace admin to grant domain-wide
delegation for these scopes in the Admin Console.

This check runs once on first tool call; subsequent calls reuse the initialized client.

check_google_auth Tool

Check connection status (always returns connected: true for service account):

Input: { requested_scopes: "drive,sheets" }
Output: {
  "connected": true,
  "current_scopes": ["https://www.googleapis.com/auth/drive", ...],
  "missing_scopes": [],
  "auth_url": null
}

Tools (52 total)

Meta

| Tool | Description | |------|-------------| | check_google_auth | Check connection status and configured scopes |

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 (optional parent folder, first sheet name) |

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 (filter by completion/due date) | | 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

Required Scopes

The Workspace admin must grant these scopes via domain-wide delegation in the Google Admin Console:

| 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 @cl0ud95/google-workspace-service-mcp

Development

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

License

MIT