{"_id":"@demitycho/google-workspace-oauth-mcp","name":"@demitycho/google-workspace-oauth-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@demitycho/google-workspace-oauth-mcp","version":"1.0.0","description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) - file-based OAuth tokens","type":"module","main":"dist/index.js","bin":{"google-workspace-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","oauth","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","_id":"@demitycho/google-workspace-oauth-mcp@1.0.0","gitHead":"3e13a0d4a1d63f93e7ed1a7e55c363313660f407","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-7omB2hNjCX4xj/HqRvkCtJkCz3AbOXfYhqAJ7pfmL2JFm7tlPp9gM9E6CuB3DbAx/fQtiXPe2GM2Ro92gW3YKQ==","shasum":"dd3abe9fdaaa076a77bab087d81315cf47fb2c0c","tarball":"https://registry.npmjs.org/@demitycho/google-workspace-oauth-mcp/-/google-workspace-oauth-mcp-1.0.0.tgz","fileCount":24,"unpackedSize":151108,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAUgxtI00990m9hR11Xn8xdr3s5iko3E/dMZsNllxaKxAiEAhNH48R6hrUxLw/KGWhkIURoEtikI+canHymWiCLCuN8="}]},"_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-oauth-mcp_1.0.0_1778344227685_0.652106426750537"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-09T16:30:27.632Z","1.0.0":"2026-05-09T16:30:27.814Z","modified":"2026-05-09T16:30:27.958Z"},"maintainers":[{"name":"demitycho","email":"tanweihao94@gmail.com"}],"description":"MCP server for Google Workspace (Drive, Sheets, Gmail, Calendar, Tasks) - file-based OAuth tokens","keywords":["mcp","google","oauth","drive","sheets","gmail","calendar","tasks","claude","ai"],"license":"MIT","readme":"# Google Workspace MCP Server\n\nMCP server providing Google Drive, Sheets, Gmail, Calendar, and Tasks access via OAuth authentication. Designed for use with Ignitive Furnace v2 control plane.\n\n## Version\n\n**1.0.0** — File-based OAuth tokens only. Simplified architecture for control plane integration.\n\n## Architecture\n\n```\nFurnace Control Plane\n  ↓ (OAuth callback writes tokens)\n/workspace/{clientId}/{agentId}/google-tokens.json\n  ↓ (mounted into agent container)\nGoogle Workspace MCP Server\n  ↓ (makes API calls)\nGoogle Workspace APIs\n```\n\n### How It Works\n\n1. **User authenticates** — Control plane OAuth callback writes tokens to fixed file path\n2. **Agent container starts** — MCP reads `GOOGLE_TOKEN_PATH` env var\n3. **MCP reads tokens** — Loads from file on first API call\n4. **MCP refreshes tokens** — Uses `google-auth-library` with 60-second proactive buffer\n5. **MCP writes tokens** — Updated tokens (including rotated refresh_token) written back to same file\n6. **No database sync** — File is single source of truth\n\nToken refresh uses Google's `OAuth2Client` with automatic persistence via event listener.\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GOOGLE_CLIENT_ID` | Yes | OAuth client ID from GCP Console |\n| `GOOGLE_CLIENT_SECRET` | Yes | OAuth client secret from GCP Console |\n| `GOOGLE_TOKEN_PATH` | Yes | Path to `google-tokens.json` file (e.g., `/workspace/{clientId}/{agentId}/google-tokens.json`) |\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## Token File Format\n\nThe control plane writes this file after OAuth callback:\n\n```json\n{\n  \"access_token\": \"\",\n  \"refresh_token\": \"1//0abc...\",\n  \"expires_at\": 0,\n  \"scope\": \"https://www.googleapis.com/auth/drive ...\"\n}\n```\n\n- `access_token` can be empty (MCP refreshes immediately)\n- `expires_at` can be 0 (triggers immediate refresh)\n- `refresh_token` is the long-lived token\n- `scope` contains all granted OAuth scopes\n\nThe MCP updates this file automatically when tokens refresh.\n\n## Tools (51 total)\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 |\n\n### Gmail (7 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 |\n| `gmail_read_thread` | R | Get all messages in thread |\n| `gmail_send_message` | W | Send email (HTML or plain text) |\n| `gmail_create_draft` | W | Create email draft |\n| `gmail_modify_labels` | W | Add/remove labels on message |\n| `gmail_list_labels` | R | List all labels |\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 |\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## OAuth Scopes\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 @ignitive/google-workspace-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## Publishing\n\n```bash\nnpm run build\nnpm publish --access public\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-ef67a4e182567c11b0497ff7660927ea"}