ADVANCED.md

Advanced Configuration

Environment Variables

User-Configured Variables

Credentials (required — use one of these methods):

Variable	Description	Example
GOOGLE_CLIENT_ID	OAuth Client ID — simplest setup, no file needed	12345.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET	OAuth Client Secret (used with GOOGLE_CLIENT_ID)	GOCSPX-...
(or place file at)	Default location: ~/.config/google-workspace-mcp/credentials.json

Optional (for customization):

Variable	Description	Default	Example
GOOGLE_WORKSPACE_MCP_TOKEN_PATH	Override token storage location	~/.config/google-workspace-mcp/tokens.json	/custom/path/tokens.json
GOOGLE_WORKSPACE_MCP_PROFILE	Named profile for credential isolation	(none)	work
GOOGLE_WORKSPACE_TOON_FORMAT	Enable TOON format for responses	false	true
DEBUG	Enable debug logging	(disabled)	google-workspace-mcp:*

System Variables

These are standard system environment variables that the application reads but you typically don't need to set:

Variable	Description	Used For
XDG_CONFIG_HOME	Linux/Unix config directory standard	Determining default token storage location
NODE_ENV	Node.js environment mode	May affect error handling and logging

Multi-Account Setup

Option 1: Named Profiles (Recommended)

Named profiles isolate credentials and tokens per Google account under ~/.config/google-workspace-mcp/profiles/<name>/.

1. Copy credentials into the profile directory:

mkdir -p ~/.config/google-workspace-mcp/profiles/work
cp credentials.json ~/.config/google-workspace-mcp/profiles/work/

2. Authenticate the profile:

npx @dguido/google-workspace-mcp auth --profile work

3. Configure your MCP client:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_WORKSPACE_MCP_PROFILE": "work"
      }
    }
  }
}

Repeat for each account (e.g., personal, work). Each profile stores its own credentials.json and tokens.json.

Profile names must be 1-64 characters: letters, digits, hyphens, underscores.

Option 2: Environment Variable Overrides

For full control, use env vars to specify credentials and tokens:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "12345.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-...",
        "GOOGLE_WORKSPACE_MCP_TOKEN_PATH": ".credentials/tokens.json"
      }
    }
  }
}

Explicit env vars always override profile paths.

When to Use Each

Approach	Best For
Default (~/.config/)	Single Google account
Named profiles	Multiple accounts, clean isolation
Environment variable overrides	Custom paths, CI/CD, advanced setups

Token Storage

Authentication tokens are stored securely following the XDG Base Directory specification:

Priority	Location	Configuration
1	Custom path	Set GOOGLE_WORKSPACE_MCP_TOKEN_PATH environment variable
2	Named profile	Set GOOGLE_WORKSPACE_MCP_PROFILE env var or --profile
3	XDG Config	$XDG_CONFIG_HOME/google-workspace-mcp/tokens.json
4	Default	~/.config/google-workspace-mcp/tokens.json

Security Notes:

• Tokens are created with secure permissions (0600)
• Never commit tokens to version control
• Tokens auto-refresh before expiration
• Google OAuth apps in "Testing" status have refresh tokens that expire after 7 days

TOON Format

TOON (Token-Oriented Object Notation) is a token-efficient encoding format designed for LLM consumption. When enabled, structured responses use TOON instead of JSON, reducing token usage by 20-50%.

Enabling TOON

GOOGLE_WORKSPACE_TOON_FORMAT=true

How It Works

TOON eliminates repeated field names in arrays. Instead of:

{
  "files": [
    { "id": "abc", "name": "doc.txt", "size": 1024 },
    { "id": "def", "name": "notes.md", "size": 2048 }
  ]
}

TOON encodes as:

files[2]{id,name,size}:
  abc,doc.txt,1024
  def,notes.md,2048

Expected Savings

Data Pattern	Token Savings
Uniform arrays (10+ items, scalar fields)	40-55%
Nested objects with uniform sub-arrays	25-35%
Deeply nested objects	20-30%
Single items	5-15%

Best Use Cases

• list_calendars, search (Drive) - uniform arrays with many fields
• list_events, search_emails - mixed structures with nested arrays
• list_labels, list_filters - large collections

Fallback Behavior

If TOON encoding fails for any reason, responses automatically fall back to JSON formatting.