1. Start the server:

   npm start

   

Optional arguments:
- --gauth-file: Path to the OAuth2 credentials file (default: ./.gauth.json)
- --accounts-file: Path to the accounts configuration file (default: ./.accounts.json)
- --credentials-dir: Directory to store OAuth credentials (default: current directory)

2. The server will start and listen for MCP commands via stdin/stdout.

3. On first run for each account, it will:
- Open a browser window for OAuth2 authentication
- Listen on port 4100 for the OAuth2 callback
- Store the credentials for future use in a file named .oauth2.{email}.json

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:

1. Create OAuth2 Credentials:
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API and Google Calendar API for your project
- Go to "Credentials" → "Create Credentials" → "OAuth client ID"
- Select "Desktop app" or "Web application" as the application type
- Configure the OAuth consent screen with required information
- Add authorized redirect URIs (include http://localhost:4100/code for local development)

2. Required OAuth2 Scopes:

   [

     "openid",

     "https://mail.google.com/",

     "https://www.googleapis.com/auth/gmail.settings.basic",

     "https://www.googleapis.com/auth/calendar",

     "https://www.googleapis.com/auth/userinfo.email"

   ]

   

3. Create a .gauth.json file in the project root with your Google OAuth 2.0 credentials:

   {

     "installed": {

       "client_id": "your_client_id",

       "project_id": "your_project_id",

       "auth_uri": "https://accounts.google.com/o/oauth2/auth",

       "token_uri": "https://oauth2.googleapis.com/token",

       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",

       "client_secret": "your_client_secret",

       "redirect_uris": ["http://localhost:4100/code"]

     }

   }

   

4. Create a .accounts.json file to specify which Google accounts can use the server:

   {

     "accounts": [

       {

         "email": "your.email@gmail.com",

         "account_type": "personal",

         "extra_info": "Primary account with Family Calendar"

       }

     ]

   }

   

You can specify multiple accounts. Make sure they have access in your Google Auth app. The extra_info field is especially useful as you can add information here that you want to tell the AI about the account (e.g., whether it has a specific calendar).

npm run authenticate -- user@gmail.com --force

npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

If installed via npm, you can also run:

Configure Claude Desktop to use the mcp-google-workspace server:

On MacOS: Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: Edit %APPDATA%/Claude/claude_desktop_config.json
<details>

  <summary>Development/Unpublished Servers Configuration</summary>

  

</details>

<details>

  <summary>Published Servers Configuration</summary>

  

- GMAIL_ALLOW_SENDING — set to true to allow gmail_send to actually send mail. Defaults to disabled.
- GMAIL_ALLOW_DRAFTS — set to true to allow draft creation tools. Defaults to disabled.
- GMAIL_ATTACHMENTS_DIR — base directory under which gmail_get_attachment and gmail_bulk_save_attachments may write files. Attachment paths supplied by the caller are treated as relative to this directory; absolute paths, traversal, and symlinks that escape the directory are rejected. Defaults to ~/.mcp-gsuite/attachments`.