Skip to main content

​
Google Workspace

Access all of Google Workspace — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and 20+ more services — through a single toolkit. Powered by the gws CLI and the Model Context Protocol, tools are discovered dynamically at runtime. When Google adds new APIs or gws ships updates, your agent picks them up automatically with zero code changes.

​
Prerequisites

1

Install the gws CLI

npm install -g @googleworkspace/cli
2

Authenticate with Google

gws auth setup    # First time: creates GCP project + OAuth + login
gws auth login    # Subsequent logins
See the gws auth docs for service accounts, CI/CD, and multi-account setup.
3

Install the MCP SDK

npm install @modelcontextprotocol/sdk

​
Quick Start

import { Agent, openai, GoogleWorkspaceToolkit } from "@radaros/core";

const gw = new GoogleWorkspaceToolkit({
  services: ["drive", "gmail", "calendar", "sheets"],
});
await gw.connect();

const agent = new Agent({
  name: "workspace-assistant",
  model: openai("gpt-4o"),
  instructions: "You help manage Google Workspace. Be concise.",
  tools: gw.getTools(),
});

const result = await agent.run("List my 5 most recent Drive files.");
console.log(result.text);

await gw.close();

​
Config

​
services
string[]
Google Workspace services to expose as tools. Use ["all"] to enable every service.
​
gwsBinaryPath
string
default:"gws"
Path to the gws binary. Override if it’s not on your PATH.
​
includeWorkflows
boolean
default:"false"
Include higher-level workflow tools (e.g., composing and sending a Gmail message, uploading to Drive with metadata).
​
includeHelpers
boolean
default:"false"
Include helper tools for common multi-step operations.
​
env
Record<string, string>
Environment variables forwarded to the gws process. Useful for overriding auth (e.g., GOOGLE_WORKSPACE_CLI_TOKEN).

​
Service Selection

Each service adds roughly 10-80 tools. Select only what you need to keep the tool set manageable: 
// Core productivity
const gw = new GoogleWorkspaceToolkit({
  services: ["drive", "gmail", "calendar", "sheets"],
});

// Extended workspace
const gw = new GoogleWorkspaceToolkit({
  services: ["drive", "gmail", "calendar", "sheets", "docs", "chat", "tasks"],
});

// Everything
const gw = new GoogleWorkspaceToolkit({
  services: ["all"],
});

​
Available Services

ServiceDescription
driveFiles, folders, permissions, shared drives
gmailMessages, threads, labels, drafts, settings
calendarEvents, calendars, ACLs
sheetsSpreadsheets, values, charts
docsDocuments, content manipulation
chatSpaces, messages, memberships
adminUsers, groups, organizational units
contactsPeople, contact groups
tasksTask lists, tasks
formsForms, responses
slidesPresentations, pages
keepNotes, lists
vaultMatters, holds, exports
groupsGroup settings
alertcenterAlerts
classroomCourses, students, teachers
meetConference records, spaces
sitesSites management

​
Using ToolRouter for Large Tool Sets

When enabling many services, use toolRouter to automatically select only the relevant tools per query. This keeps LLM prompts small and responses fast: 
const gw = new GoogleWorkspaceToolkit({ services: ["all"] });
await gw.connect();

const agent = new Agent({
  name: "workspace-assistant",
  model: openai("gpt-4o"),
  tools: gw.getTools(),
  toolRouter: {
    model: openai("gpt-4o-mini"),
    maxTools: 10,
  },
});
The ToolRouter uses a cheap model to pre-select the best 10 tools for each query before sending them to the main model.

​
Advanced: Raw MCPToolProvider

For full control over the MCP connection (custom filtering, include/exclude tools), use MCPToolProvider directly: 
import { Agent, openai, MCPToolProvider } from "@radaros/core";

const gws = new MCPToolProvider({
  name: "gws",
  transport: "stdio",
  command: "gws",
  args: ["mcp", "-s", "drive,gmail"],
});

await gws.connect();

// Filter to specific tools
const tools = await gws.getTools({
  include: ["drive_files_list", "drive_files_get", "gmail_users_messages_list"],
});

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  tools,
});

await agent.run("List my recent Drive files");
await gws.close();

​
Lifecycle

The toolkit must be connected before use and closed when done: 
const gw = new GoogleWorkspaceToolkit({ services: ["drive"] });

await gw.connect();         // Spawns gws process, discovers tools
console.log(gw.connected);  // true
console.log(gw.getTools()); // ToolDef[]

await gw.refresh();          // Re-discover tools (e.g., after gws update)
await gw.close();            // Kill gws process, clean up

​
Comparison with Individual Toolkits

RadarOS also ships dedicated toolkits for Gmail, Google Sheets, and Google Calendar. Here’s when to use which:
GoogleWorkspaceToolkitIndividual Toolkits
Coverage30+ services, 500+ API methods3-4 hand-crafted tools per service
SetupInstall gws CLI + MCP SDKInstall googleapis npm package
AuthManaged by gws (encrypted, multi-account)Manual OAuth2 credentials + token files
Tool qualityAuto-generated from API schemasHand-tuned descriptions and parameters
Dependenciesgws binary + @modelcontextprotocol/sdkgoogleapis
Best forBroad workspace access, rapid prototypingFine-grained control over specific services

​
Troubleshooting

​
”gws: command not found”

The gws CLI is not installed or not on your PATH. 
npm install -g @googleworkspace/cli
Or specify the full path: 
const gw = new GoogleWorkspaceToolkit({
  gwsBinaryPath: "/usr/local/bin/gws",
});

​
“Access blocked” during gws auth

Your OAuth app is in testing mode and your account isn’t listed as a test user. See the gws troubleshooting guide.

​
Too many tools overwhelming the LLM

Reduce the service list or use toolRouter: 
const gw = new GoogleWorkspaceToolkit({
  services: ["drive", "gmail"],  // Only what you need
});

// Or keep all services but use ToolRouter
const agent = new Agent({
  tools: gw.getTools(),
  toolRouter: { model: openai("gpt-4o-mini"), maxTools: 8 },
});