Google Workspace

You can run a code-first MCP server that executes JavaScript or TypeScript through a single tool named execute, granting authenticated access to Google Workspace APIs. This approach emphasizes programmable flexibility over many fixed tools, letting you perform diverse actions by writing small scripts that run securely within a managed runtime.

How to use

You will run the MCP server locally and connect to it with an MCP client. You provide scripts that run inside a small runtime environment where you have access to authentication helpers and Workspace APIs. Use this to perform Google Drive, Calendar, and other Workspace operations by calling the workspace helpers from your script. The server handles initial OAuth sign-in in your browser and then reuses tokens for subsequent requests.

How to install

Prerequisites: Node.js 20 or newer must be installed on your system. You also need a desktop or browser access for the initial OAuth sign-in.

npm install

Start the server with the standard run command shown in the configuration snippet.

npm start

If you prefer to run the server directly, you can start it using Node with the explicit entry point shown in the configuration.

node src/server.js

Configuration and runtime details

The server exposes a single MCP tool named execute. You provide a script body in JavaScript or TypeScript, along with optional execution parameters. The runtime offers a small API surface to access Google Workspace services and manage state across runs.

MCP configuration

The MCP configuration defines how to launch the local server from an MCP client. You will typically run the server as a local process and connect through stdio. The following example shows the configuration exactly as provided in the project.

{
  "mcpServers": {
    "google-workspace-code": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Users/mitsuhiko/Development/workspace-mcp/src/server.js"
      ],
      "env": {
        "GOOGLE_WORKSPACE_AUTH_MODE": "cloud"
      }
    }
  }
}

OAuth and token storage

On the first request without a token, the server will trigger a browser-based OAuth login. Tokens are stored for reuse on subsequent requests. The default token and config directories are used unless you override them.

Default config directory: ~/.pi/google-workspace. Default token path: ~/.pi/google-workspace/token.json. Default auth mode: cloud.

Environment variables

The server supports the following environment variables to customize behavior and authentication.

GOOGLE_WORKSPACE_CONFIG_DIR
GOOGLE_WORKSPACE_CREDENTIALS
GOOGLE_WORKSPACE_TOKEN
GOOGLE_WORKSPACE_AUTH_MODE (cloud or local)
GOOGLE_WORKSPACE_CLIENT_ID
GOOGLE_WORKSPACE_CLOUD_FUNCTION_URL
GOOGLE_WORKSPACE_CALLBACK_HOST

Available tools

execute

Runs JavaScript/TypeScript code inside a controlled runtime and provides access to authentication and Google Workspace APIs. You can customize scopes and timeout and return serialized results.

workspace.call

Call Google API endpoints (e.g., drive.files.list, calendar.events.list) through the workspace helper.

workspace.whoAmI

Retrieve information about the authenticated user, such as email.

workspace.service

Obtain a specific Google service client for API interactions.