{"_id":"@cl0ud95/google-workspace-service-mcp","_rev":"5-b2c32c0b528fe925310ba1c2b7ab734c","name":"@cl0ud95/google-workspace-service-mcp","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@cl0ud95/google-workspace-service-mcp","version":"1.0.0","keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@cl0ud95/google-workspace-service-mcp@1.0.0","maintainers":[{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"}],"bin":{"google-workspace-service-mcp":"dist/index.js"},"dist":{"shasum":"92a12bcecf8082ed279e8d296d5599f010ec340c","tarball":"https://registry.npmjs.org/@cl0ud95/google-workspace-service-mcp/-/google-workspace-service-mcp-1.0.0.tgz","fileCount":24,"integrity":"sha512-QGfCVnsAe5UvHoBqcDBNu34+1VAxkIAp3gYdjlinjv4Z+G/FGSL5vUIuJ61Q4F+QsauSImuk5iXei5TjX1ZHog==","signatures":[{"sig":"MEUCIEAG6pDGsGs9GedaUB/CCpLVXNNn1yJn400IDvc3E8i2AiEAzLBnyrZeQ/Ye9IjNkrabL8Mp8Ogzf9ZgNpfK1SXR6f4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":146331},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"c9b0a50888474513a04e43f6238fb7aecaf37144","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"},"_npmVersion":"11.6.2","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^3.24.2","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.6.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/google-workspace-service-mcp_1.0.0_1777913588275_0.749048814029555","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@cl0ud95/google-workspace-service-mcp","version":"1.1.0","keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@cl0ud95/google-workspace-service-mcp@1.1.0","maintainers":[{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"}],"bin":{"google-workspace-service-mcp":"dist/index.js"},"dist":{"shasum":"633325ab6bb32763cdf29240251c97e3eb53e5f5","tarball":"https://registry.npmjs.org/@cl0ud95/google-workspace-service-mcp/-/google-workspace-service-mcp-1.1.0.tgz","fileCount":24,"integrity":"sha512-6dKBtCayMGwXGirnzfSXavJoRyALgCY39QTbuH4evOkNLutteKvA1pInb56K6+UDATKGmKV9zCc5kIp2xUVknA==","signatures":[{"sig":"MEUCIGpyjM+ZXzvuCf6am9qUGsKZN/sIvw/mLKUA8ks+tc8iAiEA+vtAHXaXyUPWCLwhxQlZy44XpWT1e9drcM9Jrnkjn28=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":152743},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"3e13a0d4a1d63f93e7ed1a7e55c363313660f407","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"},"_npmVersion":"11.6.2","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^3.24.2","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.6.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/google-workspace-service-mcp_1.1.0_1778512321591_0.587875578948476","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@cl0ud95/google-workspace-service-mcp","version":"1.1.1","keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@cl0ud95/google-workspace-service-mcp@1.1.1","maintainers":[{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"}],"bin":{"google-workspace-service-mcp":"dist/index.js"},"dist":{"shasum":"93503a06075efd172ae18352196049cb94d0ad98","tarball":"https://registry.npmjs.org/@cl0ud95/google-workspace-service-mcp/-/google-workspace-service-mcp-1.1.1.tgz","fileCount":24,"integrity":"sha512-W0FhYttZl4vcJsc1vqEff+PlWODvUEO9aKQvqdOPLygQensPR7vVUS8PEGrlP7DI7jg9eH/DjhGc51/YwKwMdQ==","signatures":[{"sig":"MEUCIQDIwuIh2QPuN3G/s9RKBr03yIpoCMJAtnmwv0ZsJQflqgIgfNqDce/lTEhu0uWOFMDOQzG9jEDj5VrSSyjAGPuqE44=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":152907},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"b89a10f4e204653ee216b0c650dd62a560ae5eb3","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"cl0ud95","email":"wayne.hoon@ignitive.ai"},"_npmVersion":"11.6.2","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^3.24.2","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.6.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/google-workspace-service-mcp_1.1.1_1778585429329_0.3781555935104881","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-04T16:53:08.125Z","modified":"2026-05-27T05:53:44.111Z","1.0.0":"2026-05-04T16:53:08.407Z","1.1.0":"2026-05-11T15:12:01.730Z","1.1.1":"2026-05-12T11:30:29.457Z"},"license":"MIT","keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","maintainers":[{"email":"wayne.hoon@ignitive.ai","name":"ignitive-solutions"},{"email":"tanweihao94@gmail.com","name":"demitycho"}],"readme":"# Google Workspace Service Account MCP Server\n\nMCP server providing Google Drive, Sheets, Gmail, Calendar, and Tasks access via service account authentication with domain-wide delegation. Designed for Google Workspace business clients.\n\n## Version\n\n**4.0.0** — Service account-only server. Split from original dual-mode server. Removed OAuth authentication.\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph Container[\"Agent Container\"]\n        MCP[\"MCP Server (this package)\"]\n        JWT[\"google-auth-library<br/>JWT Client\"]\n        APIs[\"googleapis<br/>(Drive/Sheets/Gmail/Calendar/Tasks)\"]\n\n        MCP --> JWT\n        MCP --> APIs\n        APIs -->|\"API calls (impersonating user)\"| Google[\"Google Workspace APIs\"]\n        MCP -->|\"scope check (once)\"| TokenInfo[\"Google Tokeninfo API\"]\n    end\n\n    SA[\"Service Account JSON<br/>(key file)\"] -->|\"key file\"| JWT\n\n    style Container fill:#f3e5f5\n    style Google fill:#e8f5e9\n    style TokenInfo fill:#fff9c4\n```\n\n### How It Works\n\n1. **Agent calls MCP tool** (e.g., `drive_list_files`)\n2. **First call only** — MCP reads service account key, creates JWT client with subject impersonation, authorizes, and verifies granted scopes via Google's tokeninfo endpoint\n3. **Subsequent calls** — reuses initialized client (no refresh needed, JWT tokens are self-signed)\n4. **If scopes are missing** — returns clear error naming missing scopes and service account email (admin needs to update delegation)\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GOOGLE_SERVICE_ACCOUNT_PATH` | Yes | Path to service account JSON key file |\n| `GOOGLE_IMPERSONATE_USER` | Yes | Email address to impersonate (domain-wide delegation) |\n| `GOOGLE_ROOT_FOLDER_ID` | No | Google Drive folder ID that scopes Drive operations |\n| `GOOGLE_SERVICES` | No | Comma-separated enabled services (default: `drive,sheets,gmail,calendar,tasks`) |\n| `GOOGLE_READONLY` | No | If `true`, only read tools for Drive/Sheets (default: `false`) |\n\n## Scope Verification\n\nOn first tool call, the MCP verifies the Workspace admin has granted the required scopes via domain-wide delegation:\n\n```\nError: Service account (sa-name@project.iam.gserviceaccount.com) is missing delegated scopes:\nhttps://www.googleapis.com/auth/gmail.compose. Ask your Workspace admin to grant domain-wide\ndelegation for these scopes in the Admin Console.\n```\n\nThis check runs once on first tool call; subsequent calls reuse the initialized client.\n\n### `check_google_auth` Tool\n\nCheck connection status (always returns `connected: true` for service account):\n\n```\nInput: { requested_scopes: \"drive,sheets\" }\nOutput: {\n  \"connected\": true,\n  \"current_scopes\": [\"https://www.googleapis.com/auth/drive\", ...],\n  \"missing_scopes\": [],\n  \"auth_url\": null\n}\n```\n\n## Tools (52 total)\n\n### Meta\n\n| Tool | Description |\n|------|-------------|\n| `check_google_auth` | Check connection status and configured scopes |\n\n### Drive (16 tools)\n\n| Tool | R/W | Description |\n|------|-----|-------------|\n| `drive_list_files` | R | List files in folder (paginated) |\n| `drive_list_folders` | R | List only folders in folder |\n| `drive_get_file` | R | Get file metadata |\n| `drive_read_file` | R | Read text file content (truncates at 1MB) |\n| `drive_download` | R | Get download URL for binary files |\n| `drive_search` | R | Search files by name in root tree |\n| `drive_tree` | R | Get folder tree structure |\n| `drive_create_folder` | W | Create folder |\n| `drive_create_file` | W | Create text file |\n| `drive_update_file` | W | Update file content |\n| `drive_move_file` | W | Move file to different folder |\n| `drive_rename_file` | W | Rename file/folder |\n| `drive_delete_file` | W | Trash file/folder |\n| `drive_share_file` | W | Set link sharing (private/anyone/anyone_with_link) |\n| `drive_add_collaborator` | W | Add user as collaborator |\n| `drive_remove_collaborator` | W | Remove collaborator |\n| `drive_get_permissions` | R | Get file permissions and collaborators |\n\n### Sheets (13 tools)\n\n| Tool | R/W | Description |\n|------|-----|-------------|\n| `sheets_list` | R | List all spreadsheets in root folder |\n| `sheets_get_info` | R | Get spreadsheet metadata and sheets |\n| `sheets_get_sheet` | R | Get specific sheet/tab metadata |\n| `sheets_read_cell` | R | Read single cell |\n| `sheets_read_range` | R | Read range (truncates at 10k rows) |\n| `sheets_read_all` | R | Read entire sheet |\n| `sheets_write_cell` | W | Write single cell |\n| `sheets_write_range` | W | Write 2D array to range |\n| `sheets_append_row` | W | Append row to end of sheet |\n| `sheets_clear_range` | W | Clear range values |\n| `sheets_create_sheet` | W | Create new sheet/tab |\n| `sheets_delete_sheet` | W | Delete sheet/tab |\n| `sheets_create_spreadsheet` | W | Create new spreadsheet file (optional parent folder, first sheet name) |\n\n### Gmail (8 tools)\n\n| Tool | R/W | Description |\n|------|-----|-------------|\n| `gmail_search_messages` | R | Search messages with query |\n| `gmail_read_message` | R | Get full message with decoded body and attachment metadata |\n| `gmail_read_thread` | R | Get all messages in thread with attachment metadata |\n| `gmail_send_message` | W | Send email (HTML or plain text, optional attachments) |\n| `gmail_create_draft` | W | Create email draft (optional attachments) |\n| `gmail_modify_labels` | W | Add/remove labels on message |\n| `gmail_list_labels` | R | List all labels |\n| `gmail_get_attachment` | R | Download attachment content by messageId and attachmentId |\n\n### Calendar (8 tools)\n\n| Tool | R/W | Description |\n|------|-----|-------------|\n| `gcal_list_calendars` | R | List all calendars |\n| `gcal_list_events` | R | List events in calendar |\n| `gcal_get_event` | R | Get single event details |\n| `gcal_create_event` | W | Create new event |\n| `gcal_update_event` | W | Update existing event |\n| `gcal_delete_event` | W | Delete event |\n| `gcal_respond_to_event` | W | Accept/decline/tentative response |\n\n### Tasks (8 tools)\n\n| Tool | R/W | Description |\n|------|-----|-------------|\n| `gtasks_list_tasklists` | R | List all task lists |\n| `gtasks_get_tasklist` | R | Get a specific task list |\n| `gtasks_list_tasks` | R | List tasks in a task list (filter by completion/due date) |\n| `gtasks_get_task` | R | Get a specific task |\n| `gtasks_create_task` | W | Create a new task |\n| `gtasks_update_task` | W | Update task (title, notes, status, due date) |\n| `gtasks_delete_task` | W | Delete a task |\n| `gtasks_clear_tasks` | W | Clear all completed tasks from a list |\n\n## Service Filtering\n\nOnly register tools the agent needs — saves context tokens:\n\n```json\n\"GOOGLE_SERVICES\": \"sheets\"               // Only Sheets tools\n\"GOOGLE_SERVICES\": \"drive,sheets\"         // Drive + Sheets\n\"GOOGLE_SERVICES\": \"drive,sheets,gmail\"   // Drive + Sheets + Gmail\n```\n\n## Required Scopes\n\nThe Workspace admin must grant these scopes via domain-wide delegation in the Google Admin Console:\n\n| Service | Scope URLs |\n|---------|-----------|\n| Drive | `https://www.googleapis.com/auth/drive` |\n| Sheets | `https://www.googleapis.com/auth/spreadsheets` |\n| Gmail | `https://www.googleapis.com/auth/gmail.compose`, `https://www.googleapis.com/auth/gmail.modify` |\n| Calendar | `https://www.googleapis.com/auth/calendar` |\n| Tasks | `https://www.googleapis.com/auth/tasks` |\n\n## Installation\n\n```bash\nnpx -y @cl0ud95/google-workspace-service-mcp\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build      # Compile TypeScript\nnpm run dev        # Run with tsx\nnpm run typecheck  # Type check only\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}