From d884fab3e17eef482bee90e31c1f00e76c24ec40 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 18 Mar 2026 08:06:14 +0000 Subject: [PATCH] docs: investigate and add google workspace mcp integration This commit adds: 1. `.jules/google_workspace_mcp_investigation.md`: A detailed report covering architecture and strategy for hooking PicoClaw to Google Workspace via an external MCP server. 2. `docs/integrations/google_workspace.md`: User-facing documentation on connecting the recommended MCP servers using PicoClaw's `mcp2cli` tool or native MCP config. 3. `scripts/setup_gcp_workspace.sh`: An automated bash script that uses the `gcloud` CLI to provision a GCP project, enable Gmail, Calendar, and Drive APIs, and create a Service Account for fast headless deployment. Co-authored-by: hobbyistlabs-coder <267281733+hobbyistlabs-coder@users.noreply.github.com> --- .jules/google_workspace_mcp_investigation.md | 65 +++++++++++++ docs/integrations/google_workspace.md | 88 ++++++++++++++++++ scripts/setup_gcp_workspace.sh | 96 ++++++++++++++++++++ 3 files changed, 249 insertions(+) create mode 100644 .jules/google_workspace_mcp_investigation.md create mode 100644 docs/integrations/google_workspace.md create mode 100755 scripts/setup_gcp_workspace.sh diff --git a/.jules/google_workspace_mcp_investigation.md b/.jules/google_workspace_mcp_investigation.md new file mode 100644 index 000000000..8371ba071 --- /dev/null +++ b/.jules/google_workspace_mcp_investigation.md @@ -0,0 +1,65 @@ +# Integrating Google Workspace into PicoClaw using MCP + +## Overview + +The goal is to provide PicoClaw agents with the ability to read and mutate data in a user's Google Workspace, specifically Gmail, Google Calendar, and Google Drive. Given the requirement to keep this integration as an "off-context separate service" and the existing support for Model Context Protocol (MCP) in PicoClaw (both natively via `pkg/agent/loop_mcp.go` and dynamically via `mcp2cli`), using an external MCP Server is the recommended architectural approach. + +## Recommended External Service Architecture + +We recommend deploying a specialized Google Workspace MCP server that handles authentication and exposes tools for Gmail, Calendar, and Drive. + +There are several open-source MCP servers built for this exact purpose: +1. **[epaproditus/google-workspace-mcp-server](https://github.com/epaproditus/google-workspace-mcp-server)**: Provides robust Gmail (`list_emails`, `search_emails`, `send_email`) and Calendar APIs. +2. **[aaronsb/google-workspace-mcp](https://github.com/aaronsb/google-workspace-mcp)**: Comprehensive coverage for Gmail, Calendar, and Drive. +3. **[ghaziahamat/google-workspace-mcp](https://github.com/ghaziahamat/google-workspace-mcp)**: A Python-based collection of independent servers for Gmail, Calendar, and Drive. + +These servers can run locally via Docker, `npx`, or Python `uvx`, and PicoClaw can connect to them seamlessly using its existing `mcp2cli` tool. + +### Example PicoClaw Tool Execution via `mcp2cli` + +PicoClaw's `mcp2cli` tool allows dynamic execution without loading full JSON schemas upfront: + +```bash +# Example agent call internally +mcp2cli --mcp-stdio "npx @epaproditus/google-workspace-mcp-server" send_email --to "user@example.com" --subject "Hello" --body "Test message" +``` + +## Authentication & Onboarding Strategy + +### 1. Service Accounts (Single-Tenant / Headless Automation) + +Since you are currently testing and prefer a low-friction setup for yourself, **Service Accounts** are the easiest starting point for backend, headless automation. + +**Pros:** +- No browser popup or user interaction required at runtime. +- Excellent for cron jobs, background processing, and server-side automation. + +**Cons:** +- Requires Google Workspace **Domain-Wide Delegation**, which means you must be a Google Workspace Super Admin. +- If you are building a multi-tenant SaaS application, you cannot easily use Service Accounts to access emails of users outside your organization (e.g., public `@gmail.com` accounts). + +### 2. OAuth 2.0 User Consent (Multi-Tenant / Production) + +For a multi-tenant application where users "easily onboard their gsuite", **OAuth 2.0 Authorization Code Flow** is the industry standard. + +**Pros:** +- Users simply click "Sign in with Google", grant permissions, and return to your app. +- Works for both personal `@gmail.com` accounts and enterprise Google Workspace accounts. +- The external MCP server (or your backend) stores a `refresh_token` to make API calls on the user's behalf indefinitely. + +**Cons:** +- Requires setting up an OAuth Consent Screen in Google Cloud Console. +- Your app needs to be verified by Google if you request sensitive scopes (like Gmail read/write or Drive). + +## Automating the GCP Project Setup + +To help you get started quickly with the Service Account approach, we will provide a helper script (`scripts/setup_gcp_workspace.sh`) that automates the creation of a Google Cloud Project, enables the necessary APIs, and creates a Service Account with a downloadable JSON key. + +### The Automated Flow: +1. Authenticate with `gcloud auth login`. +2. Create a new Google Cloud Project. +3. Enable `gmail.googleapis.com`, `calendar-json.googleapis.com`, and `drive.googleapis.com`. +4. Create a Service Account (`picoclaw-workspace-agent@.iam.gserviceaccount.com`). +5. Download the `credentials.json` key file. + +*Note: After running this script, you will still need to manually configure Domain-Wide Delegation in the Google Workspace Admin Console (`admin.google.com`) to allow this Service Account to act on behalf of your email address.* \ No newline at end of file diff --git a/docs/integrations/google_workspace.md b/docs/integrations/google_workspace.md new file mode 100644 index 000000000..38e51b925 --- /dev/null +++ b/docs/integrations/google_workspace.md @@ -0,0 +1,88 @@ +# Integrating Google Workspace (Gmail, Calendar, Drive) with PicoClaw + +PicoClaw supports seamless integration with Google Workspace (Gmail, Calendar, Drive) by utilizing an external Model Context Protocol (MCP) server. By bridging an external Google Workspace MCP Server to PicoClaw, your AI assistant gains the ability to: + +* **Read, Search, and Send Emails** (Gmail) +* **Create, View, and Modify Events** (Google Calendar) +* **Search, Read, and Write Files** (Google Drive) + +This approach ensures PicoClaw remains lightweight while giving users full control over their Google Cloud API keys and authentication configuration. + +## 1. Choosing an MCP Server + +There are several open-source MCP servers built specifically for Google Workspace integration. We recommend: + +* **[aaronsb/google-workspace-mcp](https://github.com/aaronsb/google-workspace-mcp)**: Comprehensive coverage for Gmail, Calendar, and Drive. Supports both OAuth 2.0 (for Multi-Tenant/Personal) and Service Accounts (for Headless/Enterprise). +* **[epaproditus/google-workspace-mcp-server](https://github.com/epaproditus/google-workspace-mcp-server)**: Excellent for Gmail and Calendar specifically. + +## 2. Authentication Setup + +Before connecting the server, you must configure a Google Cloud Project with the necessary APIs enabled. + +### Option A: Service Accounts (Recommended for Headless / Single-Tenant) +Service Accounts are best for cron jobs or autonomous background agents since they don't require user interaction (browser logins) at runtime. However, they require you to be a Google Workspace Super Admin to grant Domain-Wide Delegation. + +To automate the creation of a Google Cloud Project, enabling the APIs, and downloading a Service Account key, run the provided helper script: + +```bash +./scripts/setup_gcp_workspace.sh +``` + +> **Important**: After running the script, you *must* follow the printed instructions to enable Domain-Wide Delegation in your Google Workspace Admin Console (`admin.google.com`), granting the Service Account access to the required scopes (e.g., `https://www.googleapis.com/auth/gmail.modify`, `https://www.googleapis.com/auth/calendar`, `https://www.googleapis.com/auth/drive`). + +### Option B: OAuth 2.0 (Recommended for Personal / Multi-Tenant) +If you want to use a standard `@gmail.com` account or build a multi-tenant app where users easily onboard, use OAuth 2.0 User Consent. + +1. Go to Google Cloud Console > APIs & Services > Credentials. +2. Create an "OAuth 2.0 Client ID" (Desktop App type). +3. Download the `client_secrets.json` file. +4. When the MCP server starts, it will provide a link to authenticate in your browser. + +## 3. Configuring PicoClaw to Use the Server + +You can connect the chosen Google Workspace MCP Server to PicoClaw using the native `mcp2cli` tool. + +### Using `mcp2cli` dynamically + +If you want the agent to call the tools on the fly without heavy upfront JSON configuration, enable the `mcp2cli` tool in your `~/.picoclaw/config.json`: + +```json +{ + "tools": { + "mcp2cli": { + "enabled": true + } + } +} +``` + +Now, the agent can dynamically connect and execute tools. For example, the agent might automatically execute: + +```bash +mcp2cli --mcp-stdio "npx @epaproditus/google-workspace-mcp-server" --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json list_emails +``` + +### (Alternative) Using the Native MCP Manager (`pkg/agent/loop_mcp.go`) + +If you want the Gmail/Calendar/Drive tools to be natively registered inside PicoClaw as top-level tools instead of running them via the CLI tool, configure the native MCP block in your `~/.picoclaw/config.json`: + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "google_workspace": { + "command": "npx", + "args": ["-y", "@epaproditus/google-workspace-mcp-server"], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json" + } + } + } + } + } +} +``` + +When PicoClaw boots, it will connect to the MCP server, retrieve the `send_email`, `list_emails`, and `create_event` tools, and register them directly with the LLM as `mcp_google_workspace_send_email`, etc. \ No newline at end of file diff --git a/scripts/setup_gcp_workspace.sh b/scripts/setup_gcp_workspace.sh new file mode 100755 index 000000000..e48f7bede --- /dev/null +++ b/scripts/setup_gcp_workspace.sh @@ -0,0 +1,96 @@ +#!/bin/bash + +# setup_gcp_workspace.sh +# Automates the creation of a Google Cloud Project, enabling required APIs for Google Workspace, +# and creating a Service Account for use with an MCP Server. + +set -e + +echo "🚀 Starting Google Cloud Project Setup for Google Workspace MCP..." + +# Check for gcloud CLI +if ! command -v gcloud &> /dev/null; then + echo "❌ Error: Google Cloud SDK (gcloud) is not installed." + echo "Please install it from: https://cloud.google.com/sdk/docs/install" + exit 1 +fi + +echo "🔹 Checking authentication..." +# Check if user is authenticated +if ! gcloud auth print-access-token &> /dev/null; then + echo "You need to log in to Google Cloud. Opening browser..." + gcloud auth login +fi + +# Ask for a project ID +read -p "Enter a new Project ID (e.g., picoclaw-workspace-mcp): " PROJECT_ID + +if [ -z "$PROJECT_ID" ]; then + echo "❌ Error: Project ID cannot be empty." + exit 1 +fi + +echo "🔹 Creating Google Cloud Project '$PROJECT_ID'..." +if gcloud projects create "$PROJECT_ID" --name="PicoClaw Workspace MCP"; then + echo "✅ Project created successfully." +else + echo "⚠️ Project may already exist or there was an error. Proceeding to set it as default..." +fi + +echo "🔹 Setting '$PROJECT_ID' as the default project..." +gcloud config set project "$PROJECT_ID" + +# Enable billing prompt (required for some APIs, though these are mostly free tier) +echo "⚠️ Note: Some APIs may require a billing account to be linked to the project." +echo "If the next step fails, you may need to link a billing account in the Google Cloud Console:" +echo "👉 https://console.cloud.google.com/billing/linkedaccount?project=$PROJECT_ID" + +echo "🔹 Enabling required Google Workspace APIs..." +# Enable Gmail, Calendar, and Drive APIs +gcloud services enable gmail.googleapis.com +gcloud services enable calendar-json.googleapis.com +gcloud services enable drive.googleapis.com +echo "✅ APIs enabled (Gmail, Calendar, Drive)." + +# Create Service Account +SA_NAME="picoclaw-agent" +SA_EMAIL="$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com" +KEY_FILE="credentials.json" + +echo "🔹 Creating Service Account '$SA_NAME'..." +if ! gcloud iam service-accounts describe "$SA_EMAIL" &> /dev/null; then + gcloud iam service-accounts create "$SA_NAME" \ + --description="Service account for PicoClaw MCP Google Workspace integration" \ + --display-name="PicoClaw Agent Service Account" + echo "✅ Service account created: $SA_EMAIL" +else + echo "✅ Service account already exists: $SA_EMAIL" +fi + +echo "🔹 Generating JSON key file for the Service Account..." +if [ -f "$KEY_FILE" ]; then + echo "⚠️ Key file '$KEY_FILE' already exists. Saving as new-credentials.json instead." + KEY_FILE="new-credentials.json" +fi + +gcloud iam service-accounts keys create "$KEY_FILE" \ + --iam-account="$SA_EMAIL" + +echo "🎉 Setup Complete!" +echo "Your Service Account key has been saved to: $KEY_FILE" +echo "" +echo "================================================================" +echo "⚠️ IMPORTANT: Domain-Wide Delegation Required" +echo "================================================================" +echo "To use this Service Account to access user emails and calendars," +echo "you must enable Domain-Wide Delegation in your Google Workspace Admin Console." +echo "" +echo "1. Go to: https://admin.google.com/ac/owl/domainwidedelegation" +echo "2. Click 'Add new'" +echo "3. Enter the Client ID for the Service Account (found in $KEY_FILE)" +echo "4. Add the following OAuth scopes (comma separated):" +echo " https://www.googleapis.com/auth/gmail.modify, \\" +echo " https://www.googleapis.com/auth/calendar, \\" +echo " https://www.googleapis.com/auth/drive" +echo "================================================================" +echo "Once configured, you can pass this $KEY_FILE to your chosen MCP server."