{"id":51152655,"url":"https://github.com/jakubriegel/google-workspace-official-mcp-tutorial","last_synced_at":"2026-06-26T07:04:07.972Z","repository":{"id":340168896,"uuid":"1164860818","full_name":"jakubriegel/google-workspace-official-mcp-tutorial","owner":"jakubriegel","description":"Step-by-step tutorial for setting up the official Google Workspace MCP server with AI agents, including Gmail MCP, Google Docs, Drive, and Calendar integration.","archived":false,"fork":false,"pushed_at":"2026-02-23T15:31:21.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-23T23:39:28.149Z","etag":null,"topics":["ai-agents","gmail","google","googleworkspace","mcp","mcp-server","openclaw"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jakubriegel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T15:08:15.000Z","updated_at":"2026-02-23T15:33:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jakubriegel/google-workspace-official-mcp-tutorial","commit_stats":null,"previous_names":["jakubriegel/google-workspace-official-mcp-tutorial"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jakubriegel/google-workspace-official-mcp-tutorial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakubriegel%2Fgoogle-workspace-official-mcp-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakubriegel%2Fgoogle-workspace-official-mcp-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakubriegel%2Fgoogle-workspace-official-mcp-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakubriegel%2Fgoogle-workspace-official-mcp-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakubriegel","download_url":"https://codeload.github.com/jakubriegel/google-workspace-official-mcp-tutorial/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakubriegel%2Fgoogle-workspace-official-mcp-tutorial/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34806450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","gmail","google","googleworkspace","mcp","mcp-server","openclaw"],"created_at":"2026-06-26T07:04:07.508Z","updated_at":"2026-06-26T07:04:07.965Z","avatar_url":"https://github.com/jakubriegel.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Workspace MCP Server Tutorial for AI Agents on macOS (Gmail, Docs, Drive, Calendar) 🔧✨\n\nThis step-by-step tutorial shows how to run **gemini-cli-extensions/workspace** (official MCP tool from Google) as a **local MCP (Model Context Protocol) server** and connect it to an MCP-compatible AI client.\nIt is focused on common Google Workspace MCP and Gmail MCP setup queries on macOS, including OAuth login loops and localhost redirect issues.\n\n---\n\n## What you get ✅\n\nAfter setup, your AI client can call Google Workspace tools such as:\n\n- Google Docs (`docs.create`, `docs.getText`, …)\n- Drive (`drive.search`, `drive.createFolder`, …)\n- Gmail (`gmail.search`, draft/send helpers, …)\n- Calendar (`calendar.getEvents`, …)\n- Sheets/Slides/People/Chat (varies by tool set)\n\n---\n\n## Prerequisites 🧰\n\nYou need:\n\n1) **Git**\n2) **Node.js + npm** (recommended: Node 22+)\n3) **An MCP-compatible AI client** installed\n4) A **Google Cloud Project** with billing enabled\n5) `gcloud` installed and authenticated\n\n---\n\n## Part A - Get the repo locally 📦\n\n1) Clone the repo:\n\n```bash\ngit clone https://github.com/gemini-cli-extensions/workspace.git\ncd workspace\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\nThat’s it for the code installation.\n\n---\n\n## Part B - Set up authentication backend (self-hosted on GCP) 🔑\n\n1. From the **repo root** (important!), run:\n\n```bash\n./scripts/setup-gcp.sh\n```\n\n\u003e If you see `Invalid value for [--source]: Provided directory does not exist`\n\u003e it usually means you ran the script **outside** the repo root. `cd workspace` first.\n\n2. When it finishes, it prints values for:\n\n* `WORKSPACE_CLIENT_ID`\n* `WORKSPACE_CLOUD_FUNCTION_URL`\n\n3. Export those values in your shell (or put them into your MCP client config as env vars):\n\n```bash\nexport WORKSPACE_CLIENT_ID=\"your-client-id\"\nexport WORKSPACE_CLOUD_FUNCTION_URL=\"https://your-cloud-function-url\"\n```\n\n---\n\n## Part C - Force encrypted-file token storage 🔒\n\nThis avoids OS keychain issues and keeps everything local + predictable.\n\nSet:\n\n```bash\nexport GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true\n```\n\nWhat this does:\n\n* Tokens are stored in the repo root as:\n\n  * `gemini-cli-workspace-token.json` (encrypted)\n  * `.gemini-cli-workspace-master-key` (local key)\n\n---\n\n## Part D - Add the MCP server to AI Agent 🧩\n\nUse the same server values in every agent:\n\n* `command`: `node`\n* `args`: `[\"scripts/start.js\"]`\n* `cwd`: absolute path to your cloned `workspace` folder\n* env vars:\n  * `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE = \"true\"`\n  * `WORKSPACE_CLIENT_ID = \"your-client-id\"`\n  * `WORKSPACE_CLOUD_FUNCTION_URL = \"https://your-cloud-function-url\"`\n\n### Example 1: Codex (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.google_workspace]\ncommand = \"node\"\nargs = [\"scripts/start.js\"]\ncwd = \"/ABSOLUTE/PATH/TO/workspace\"\nstartup_timeout_sec = 60\n\n[mcp_servers.google_workspace.env]\nGEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE = \"true\"\nWORKSPACE_CLIENT_ID = \"your-client-id\"\nWORKSPACE_CLOUD_FUNCTION_URL = \"https://your-cloud-function-url\"\n```\n\n### Example 2: Cloude (`~/.cloude/mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"google_workspace\": {\n      \"command\": \"node\",\n      \"args\": [\"scripts/start.js\"],\n      \"cwd\": \"/ABSOLUTE/PATH/TO/workspace\",\n      \"env\": {\n        \"GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE\": \"true\",\n        \"WORKSPACE_CLIENT_ID\": \"your-client-id\",\n        \"WORKSPACE_CLOUD_FUNCTION_URL\": \"https://your-cloud-function-url\"\n      }\n    }\n  }\n}\n```\n\n### Example 3: OpenClaw (`~/.openclaw/config.yaml`)\n\n```yaml\nmcp_servers:\n  google_workspace:\n    command: node\n    args:\n      - scripts/start.js\n    cwd: /ABSOLUTE/PATH/TO/workspace\n    env:\n      GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE: \"true\"\n      WORKSPACE_CLIENT_ID: \"your-client-id\"\n      WORKSPACE_CLOUD_FUNCTION_URL: \"https://your-cloud-function-url\"\n```\n\nNotes:\n\n* `scripts/start.js` runs `npm install` (if needed) and then starts the MCP server.\n* If your agent uses different key names, map the same values from the examples above.\n\n---\n\n## Part E - First run + login flow (Google Workspace/Gmail MCP) 🌐\n\n### Normal flow (best case) ✅\n\n1. Start your AI client.\n2. Ask it to use any Workspace tool (for example: “Create a Google Doc titled Test”).\n3. A browser window opens → sign into Google.\n4. After success, the MCP server stores tokens (encrypted file).\n5. Next tool call should *not* require login again.\n\n### If Google Workspace or Gmail MCP keeps opening browser login 🐛\n\nUsually means the client/server can’t reuse tokens (not stored, missing refresh token, wrong environment, or missing scopes).\nIf you hit serious troubles, contact me at `riegel@deltologic.com`.\n\nDo these checks in order:\n\n---\n\n## Part F - Verify token persistence (fix repeated Gmail MCP login) 🔍\n\nFrom the repo root:\n\n```bash\nnpm run auth-utils -- status\n```\n\nYou want to see:\n\n* Access Token: ✅ Present\n* Refresh Token: ✅ Present\n* Status: ✅ Valid (or expired but refreshable)\n\nIf Refresh Token is missing, you’ll re-login every time.\n\n---\n\n## Part G - If Google Workspace MCP localhost redirect breaks (remote/container setup on MacOS) 🧯\n\nSymptom:\n\n* Login redirects to something like `http://localhost:\u003cport\u003e/oauth2callback...`\n* But nothing is listening on that port (because the MCP server runs elsewhere).\n\n### Fix: Force “manual” login mode 🧾\n\nSet these env vars for the MCP server.\nCodex TOML example (for Cloude and OpenClaw, set the same values in the configs from Part D):\n\n```toml\n[mcp_servers.google_workspace.env]\nCI = \"true\"\nGEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE = \"true\"\n```\n\nNow, instead of trying to complete a localhost callback, the server prints a URL.\n\n1. Run a tool again.\n2. Open the printed URL in a browser and log in.\n3. You’ll get a JSON blob containing tokens.\n\n### Import that JSON into encrypted-file storage ✅\n\n1. Save the JSON to a local file, e.g. `creds.json` (DO NOT COMMIT IT).\n\n2. Run:\n\n```bash\n# From repo root:\nnpm run build:auth-utils -w workspace-server\n\nnode -e 'const {OAuthCredentialStorage}=require(\"./workspace-server/dist/auth-utils.js\"); const creds=require(\"./creds.json\"); OAuthCredentialStorage.saveCredentials(creds).then(()=\u003econsole.log(\"✅ saved\")).catch(e=\u003e{console.error(e); process.exit(1);});'\n```\n\n3. Confirm:\n\n```bash\nnpm run auth-utils -- status\n```\n\nNow your AI client should stop re-opening login pages.\n\n---\n\n\n## Part H - Quick sanity test prompts 🧪\n\nTry these after setup:\n\n* “List my next 5 calendar events.”\n* “Search Gmail for unread emails from the last 7 days.”\n* “Find a Google Drive file named ‘README’.”\n\nIf these work without repeated login, you’re done ✅🎉\n\n---\n\n## FAQ - Google Workspace/Gmail MCP quick answers\n\n**How do I set up Google Workspace MCP on macOS?**\nFollow Part A through Part D.\n\n**Why does Gmail MCP ask me to log in every time?**\nUsually the refresh token is missing or invalid. Check Part F, then Part G.\n\n**How do I fix localhost OAuth callback issues for Google Workspace MCP?**\nUse manual login mode (`CI=true`) from Part G.\n\n**Which Google tools does this MCP server support?**\nGmail, Google Docs, Drive, Calendar, Sheets, Slides, People, and Chat (depends on enabled tools).\n\n---\n\nWe also build advanced AI agents and automations.\nContact me at `riegel@deltologic.com`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakubriegel%2Fgoogle-workspace-official-mcp-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakubriegel%2Fgoogle-workspace-official-mcp-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakubriegel%2Fgoogle-workspace-official-mcp-tutorial/lists"}