{"_id":"@demitycho/google-workspace-service-mcp","_rev":"2-521ef02bbfce40bb755224a02baadb31","name":"@demitycho/google-workspace-service-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"4.0.0":{"name":"@demitycho/google-workspace-service-mcp","version":"4.0.0","keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@demitycho/google-workspace-service-mcp@4.0.0","maintainers":[{"name":"demitycho","email":"tanweihao94@gmail.com"}],"bin":{"google-workspace-service-mcp":"dist/index.js"},"dist":{"shasum":"8b48b267161e776982afc92cd36a8272da91736f","tarball":"https://registry.npmjs.org/@demitycho/google-workspace-service-mcp/-/google-workspace-service-mcp-4.0.0.tgz","fileCount":24,"integrity":"sha512-n6YlUX2PkdOO/snGGuIe14lbs2b3IWgztP8X+P3Nd2Uzc2/v3p7L4BSSWujEYWCexyAQhY6Vit4PkbqDiceecA==","signatures":[{"sig":"MEUCIQDSjdGkWMSuzZN09B4SwmS0r2N+AwPZKjzCZ5KFcjtCIwIgco6itfTpOy4NQA1EF4ERwrpXxFafua5ptmpUV962hf0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":146333},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"c7c36ada4e8b129c23e361ee7dd94d0f35b0895d","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"demitycho","email":"tanweihao94@gmail.com"},"_npmVersion":"10.9.7","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","directories":{},"_nodeVersion":"22.22.2","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_4.0.0_1779711092804_0.17219972012190365","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@demitycho/google-workspace-service-mcp","version":"1.0.0","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) with service account authentication","type":"module","main":"dist/index.js","bin":{"google-workspace-service-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.6.1","googleapis":"^144.0.0","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.0.0","typescript":"^5.7.0"},"types":"dist/index.d.ts","engines":{"node":">=20"},"keywords":["mcp","google","service-account","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@demitycho/google-workspace-service-mcp@1.0.0","gitHead":"5fa580c7105ba29d556160339ad8789d1a1ee289","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-Vg/5pcXun62d7wcYinz4siKLEgJ943tu2A+ydE7JoXOYmbNdTOTAaKLtYBWDEECTnXMrNg97uznPzio6ys5RJA==","shasum":"621c4053ebb7ecc108e9fbd69d5b872169e8fc0e","tarball":"https://registry.npmjs.org/@demitycho/google-workspace-service-mcp/-/google-workspace-service-mcp-1.0.0.tgz","fileCount":24,"unpackedSize":152909,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICP6hLJnwgGjyqv2IL4pud2oKTrUTYaTb6TLV9dVQRkxAiBZkVfyKvae5+vq6hxOB6GhcTCIgnSbeR408qxHE3Zf1g=="}]},"_npmUser":{"name":"demitycho","email":"tanweihao94@gmail.com"},"directories":{},"maintainers":[{"name":"demitycho","email":"tanweihao94@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/google-workspace-service-mcp_1.0.0_1779863683394_0.36480232553730074"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T12:11:32.651Z","modified":"2026-05-27T06:34:43.656Z","4.0.0":"2026-05-25T12:11:32.950Z","1.0.0":"2026-05-27T06:34:43.546Z"},"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":[{"name":"demitycho","email":"tanweihao94@gmail.com"}],"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"}