{"_id":"@blackenedd18/google-workspace-mcp","_rev":"2-3c26a3a38a02237d08b5bdd7474be265","name":"@blackenedd18/google-workspace-mcp","dist-tags":{"latest":"2.4.1"},"versions":{"2.4.0":{"name":"@blackenedd18/google-workspace-mcp","version":"2.4.0","_id":"@blackenedd18/google-workspace-mcp@2.4.0","maintainers":[{"name":"blackenedd18","email":"blackenedd18@gmail.com"}],"homepage":"https://github.com/russellorv/google-workspace-mcp#readme","bugs":{"url":"https://github.com/russellorv/google-workspace-mcp/issues"},"bin":{"google-workspace-mcp":"build/index.js"},"dist":{"shasum":"6cbc2dc84801199ad862139c5eb65695b91d4209","tarball":"https://registry.npmjs.org/@blackenedd18/google-workspace-mcp/-/google-workspace-mcp-2.4.0.tgz","fileCount":286,"integrity":"sha512-bVeltpMxZkCDk383EUx28fPFUgTT2ohYWIvQKgcGonnYnEdRoCUsmtJZ9MqXsJIwoos6ijVUzxFjeoXgdiSH7g==","signatures":[{"sig":"MEUCIBfh5yGt/waeL233vcBSPY7BaDX8NGa7RtmLnA/t90vkAiEAtJmTXx1+SN4esBCf3pRUDuCZZ7MRlmMNn3NFbVYB65s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1082241},"type":"module","gitHead":"6ac2b722eb15f3eab94f73b1c09a9b3749f7112a","scripts":{"lint":"eslint \"src/**/*.ts\"","test":"jest --config jest.config.cjs --runInBand","build":"tsc --skipLibCheck && cp src/factory/manifest.yaml build/factory/","watch":"tsc --watch --skipLibCheck","prepare":"tsc --skipLibCheck && cp src/factory/manifest.yaml build/factory/","test:watch":"jest --config jest.config.cjs --watch --runInBand","type-check":"tsc --noEmit --skipLibCheck"},"_npmUser":{"name":"blackenedd18","email":"blackenedd18@gmail.com"},"repository":{"url":"git+https://github.com/russellorv/google-workspace-mcp.git","type":"git"},"_npmVersion":"11.5.1","description":"MCP server for Google Workspace with progressive context disclosure and multi-account orchestration","directories":{},"_nodeVersion":"24.5.0","dependencies":{"yaml":"^2.8.2","typescript":"~5.4.0","@googleworkspace/cli":"^0.22.3","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","ts-jest":"^29.2.5","@types/jest":"^29.5.14","@types/node":"^20.11.24","@typescript-eslint/parser":"^6.21.0","@typescript-eslint/eslint-plugin":"^6.21.0"},"_npmOperationalInternal":{"tmp":"tmp/google-workspace-mcp_2.4.0_1775652898137_0.5206731303880838","host":"s3://npm-registry-packages-npm-production"}},"2.4.1":{"name":"@blackenedd18/google-workspace-mcp","version":"2.4.1","description":"MCP server for Google Workspace with progressive context disclosure and multi-account orchestration","repository":{"type":"git","url":"git+https://github.com/russellorv/google-workspace-mcp.git"},"type":"module","bin":{"google-workspace-mcp":"build/index.js"},"scripts":{"prepare":"tsc --skipLibCheck && cp src/factory/manifest.yaml build/factory/","build":"tsc --skipLibCheck && cp src/factory/manifest.yaml build/factory/","type-check":"tsc --noEmit --skipLibCheck","lint":"eslint \"src/**/*.ts\"","watch":"tsc --watch --skipLibCheck","test":"jest --config jest.config.cjs --runInBand","test:watch":"jest --config jest.config.cjs --watch --runInBand"},"dependencies":{"@googleworkspace/cli":"^0.22.3","@modelcontextprotocol/sdk":"^1.27.1","typescript":"~5.4.0","yaml":"^2.8.2"},"devDependencies":{"@types/jest":"^29.5.14","@types/node":"^20.11.24","@typescript-eslint/eslint-plugin":"^6.21.0","@typescript-eslint/parser":"^6.21.0","eslint":"^8.56.0","jest":"^29.7.0","ts-jest":"^29.2.5"},"_id":"@blackenedd18/google-workspace-mcp@2.4.1","gitHead":"6ac2b722eb15f3eab94f73b1c09a9b3749f7112a","bugs":{"url":"https://github.com/russellorv/google-workspace-mcp/issues"},"homepage":"https://github.com/russellorv/google-workspace-mcp#readme","_nodeVersion":"24.5.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-NCZq5oLR5FidmlnyVjT2K1ZlED1kDJ1zcYMdwQ58dfR/9QVl6lKNQbSUdnmIOhvldLxo80Q3wrcQ4cVMAmF1+w==","shasum":"a2e698fd679cbfd0511dd8cb813ad3a5f2d1228e","tarball":"https://registry.npmjs.org/@blackenedd18/google-workspace-mcp/-/google-workspace-mcp-2.4.1.tgz","fileCount":286,"unpackedSize":1082513,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB+Y1Q62Onc3Yg16QedihbkYH1r0Cn1KKDGO4/ozs2OxAiBItXLbqp69mjSJVE4H38oRnAtqMJM7W7gRfPncz9JL9A=="}]},"_npmUser":{"name":"blackenedd18","email":"blackenedd18@gmail.com"},"directories":{},"maintainers":[{"name":"blackenedd18","email":"blackenedd18@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/google-workspace-mcp_2.4.1_1775653473435_0.9824381772490913"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-08T12:54:58.052Z","modified":"2026-04-08T13:04:33.678Z","2.4.0":"2026-04-08T12:54:58.377Z","2.4.1":"2026-04-08T13:04:33.576Z"},"bugs":{"url":"https://github.com/russellorv/google-workspace-mcp/issues"},"homepage":"https://github.com/russellorv/google-workspace-mcp#readme","repository":{"type":"git","url":"git+https://github.com/russellorv/google-workspace-mcp.git"},"description":"MCP server for Google Workspace with progressive context disclosure and multi-account orchestration","maintainers":[{"name":"blackenedd18","email":"blackenedd18@gmail.com"}],"readme":"# Google Workspace MCP Server\n\nGive AI agents full access to Google Workspace — Gmail, Calendar, Drive, and more — through a single MCP server that handles multi-account credential routing, response formatting for AI consumption, and contextual guidance.\n\n> **Fork notice:** This repository/package is a fork of [aaronsb/google-workspace-mcp](https://github.com/aaronsb/google-workspace-mcp), maintained and published as [`@blackenedd18/google-workspace-mcp`](https://www.npmjs.com/package/@blackenedd18/google-workspace-mcp).\n\nBuilt on [Google's official Workspace CLI](https://github.com/googleworkspace/cli) (`gws`), which means API coverage grows as Google does. The server uses a manifest-driven factory that turns declarative YAML into fully functional MCP tools — adding a new Google API operation is a config change, not a code change.\n\n## Why This MCP Server\n\n**For users:** One install gives your AI agent real, authenticated access to your Google accounts. Search email, check your calendar, manage Drive files, chain multi-step workflows — all through natural conversation.\n\n**For teams:** Multi-account support means your agent can work across personal and work accounts simultaneously, with per-account credential isolation and XDG-compliant storage.\n\n**For developers:** The factory architecture means coverage expands fast. Google's Workspace CLI already supports 15+ services and hundreds of API operations. The manifest curates which ones are exposed, patches add domain-specific formatting, and the defaults handle everything else.\n\n## What's Available\n\n**5 tools, 32+ operations across 3 core services:**\n\n| Tool | Operations | What It Does |\n|------|-----------|--------------|\n| `manage_email` | search, read, send, reply, replyAll, forward, triage, trash, untrash, modify, labels, threads, getThread | Full Gmail — search, read, compose, thread management, label management |\n| `manage_calendar` | list, agenda, get, create, quickAdd, update, delete, calendars, freebusy | Calendar CRUD, natural language event creation, availability checks |\n| `manage_drive` | search, get, upload, download, copy, delete, export, listPermissions, share, unshare | File management, Google Docs export, sharing and permissions |\n| `manage_accounts` | list, authenticate, remove, status, refresh, scopes | Multi-account lifecycle — add accounts, manage credentials and scopes |\n| `queue_operations` | — | Chain operations sequentially with `$N.field` result references |\n\nEvery response includes **next-steps** guidance — the agent always knows what it can do next.\n\n## How It Works\n\n```\n                          ┌─────────────────────────┐\nMCP Client ──stdio──▶     │  manifest.yaml           │\n                          │  (52 operations declared) │\n                          └────────┬────────────────┘\n                                   │\n                          ┌────────▼────────────────┐\n                          │  Factory Generator       │\n                          │  schemas + handlers      │\n                          └────────┬────────────────┘\n                                   │\n                    ┌──────────────┼──────────────┐\n                    ▼              ▼              ▼\n              ┌──────────┐  ┌──────────┐  ┌──────────┐\n              │  Gmail   │  │ Calendar │  │  Drive   │\n              │  Patch   │  │  Patch   │  │  Patch   │\n              └────┬─────┘  └────┬─────┘  └────┬─────┘\n                   │             │             │\n                   └──────┬──────┘──────┬──────┘\n                          ▼             ▼\n                    Account Router ──▶ gws CLI ──▶ Google APIs\n```\n\nThe **factory** reads a YAML manifest and generates MCP tool schemas and request handlers at startup. **Patches** add domain-specific behavior where needed — Gmail search hydration, calendar formatting, Drive file type detection. Operations without patches get sensible defaults automatically.\n\nThe underlying engine is Google's `@googleworkspace/cli` — a Rust binary that wraps the full Google Workspace API surface. The MCP server curates which operations to expose and shapes the responses for AI consumption.\n\n## Install\n\n### MCPB Bundle (Claude Desktop and other MCP clients)\n\nDownload the `.mcpb` bundle for your platform from the [latest release](https://github.com/aaronsb/google-workspace-mcp/releases):\n\n| Platform | File |\n|----------|------|\n| macOS (Apple Silicon) | `google-workspace-mcp-darwin-arm64.mcpb` |\n| macOS (Intel) | `google-workspace-mcp-darwin-x64.mcpb` |\n| Linux x64 | `google-workspace-mcp-linux-x64.mcpb` |\n| Linux ARM64 | `google-workspace-mcp-linux-arm64.mcpb` |\n| Windows x64 | `google-workspace-mcp-windows-x64.mcpb` |\n\nIn Claude Desktop, drag the `.mcpb` file into the app — it will prompt you for your Google OAuth credentials, then you're ready to go. Other MCP clients that support `.mcpb` extensions can install it the same way. The bundle includes everything: the server, the gws binary, and all dependencies.\n\n### Claude Code / npm\n\n```bash\nnpm install @blackenedd18/google-workspace-mcp\n```\n\nOr run directly:\n\n```bash\nnpx @blackenedd18/google-workspace-mcp\n```\n\n### Prerequisites\n\n1. **Node.js** 18+\n2. **Google Cloud OAuth credentials** — create at [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials):\n   - Create an OAuth 2.0 Client ID (Desktop application)\n   - Enable the APIs you want (Gmail, Calendar, Drive, Sheets, etc.)\n\n3. Set environment variables:\n   ```bash\n   export GOOGLE_CLIENT_ID=\"your-client-id\"\n   export GOOGLE_CLIENT_SECRET=\"your-client-secret\"\n   ```\n\n## MCP Client Configuration\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-workspace\": {\n      \"command\": \"npx\",\n      \"args\": [\"@blackenedd18/google-workspace-mcp\"],\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"your-client-id\",\n        \"GOOGLE_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-workspace\": {\n      \"command\": \"npx\",\n      \"args\": [\"@blackenedd18/google-workspace-mcp\"],\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"your-client-id\",\n        \"GOOGLE_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\n## Usage\n\nAdd an account (opens browser for OAuth):\n\n```\nmanage_accounts { \"operation\": \"authenticate\" }\n```\n\nThen use any tool with your account email:\n\n```\nmanage_email    { \"operation\": \"triage\", \"email\": \"you@gmail.com\" }\nmanage_calendar { \"operation\": \"agenda\", \"email\": \"you@gmail.com\" }\nmanage_drive    { \"operation\": \"search\", \"email\": \"you@gmail.com\", \"query\": \"quarterly report\" }\n```\n\n### Multi-Step Workflows\n\nChain operations with result references — the output of one step feeds the next:\n\n```json\n{\n  \"operations\": [\n    { \"tool\": \"manage_email\", \"args\": { \"operation\": \"search\", \"email\": \"you@gmail.com\", \"query\": \"from:boss subject:review\" }},\n    { \"tool\": \"manage_email\", \"args\": { \"operation\": \"read\", \"email\": \"you@gmail.com\", \"messageId\": \"$0.messageId\" }}\n  ]\n}\n```\n\n## Expanding Coverage\n\nThe server discovers operations from the gws CLI, which already supports 15+ Google services (Sheets, Docs, Tasks, People, Chat, and more). Adding coverage is a manifest edit:\n\n```bash\nmake manifest-discover   # Find all 287+ available operations\nmake manifest-lint       # Validate the curated manifest\nmake test                # Verify everything works\n```\n\nNew operations get default formatting automatically. Add a patch only when you need domain-specific presentation.\n\n## Data Storage\n\nFollows XDG Base Directory Specification:\n\n| Data | Location |\n|------|----------|\n| Account registry | `~/.config/google-workspace-mcp/accounts.json` |\n| Credentials | `~/.local/share/google-workspace-mcp/credentials/` |\n\nCredentials are per-account files with standard OAuth tokens. No secrets are stored in the project directory.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}