google-workspace-mcp

A local MCP server that provides access to Google Drive, Sheets, Docs, Calendar, and Gmail via OAuth2. Compatible with any MCP client (Claude Desktop, Continued, or other AI agents). Runs as a local process (stdio).

Available Tools

Related MCP server: gdrive-mcp-server

1. Setup Google Cloud Project

1. Open Google Cloud Console and create a new project (or use an existing one).

2. Enable the following APIs in APIs & Services > Library:

   • Google Drive API

   • Google Sheets API

   • Google Docs API

   • Google Calendar API

   • Gmail API

3. Go to APIs & Services > OAuth consent screen:

   • Select External (unless you use Google Workspace organization and want Internal).

   • Fill in the application name, support email, etc.

   • In the Scopes section, add scopes appropriate for this server (see src/google_workspace_mcp/auth.py), or skip it — scopes will be requested automatically during the first consent flow.

   • In the Test users section (if your app is still in "Testing" status), add your Google account email.

4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID:

   • Application type: Desktop app.

   • Give it any name, for example "Google Workspace MCP".

   • After creation, click Download JSON.

Important note: While your app is in "Testing" status on the consent screen, OAuth tokens will expire every 7 days and you'll need to re-authenticate (delete token.json and run again). For long-term use, publish your app to "In production" status on the OAuth consent screen. (Google approval is not required for personal use with non-sensitive scopes, but Drive/Gmail/Calendar are considered sensitive scopes — Google may ask for verification if you publish for many users; for solo use, Testing status + weekly re-auth is usually sufficient).

2. Installation

cd google_workspace_mcp
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

3. Store Credentials

There are two ways to provide your OAuth client ID/secret to the server — choose one.

Option A — via env in MCP config (no JSON file needed on disk):

Set GOOGLE_WORKSPACE_MCP_CLIENT_ID and GOOGLE_WORKSPACE_MCP_CLIENT_SECRET directly in the env block of your MCP server configuration (see section 5). If both are set, the server will use these and won't look for credentials.json at all.

Option B — credentials.json file on disk:

Save the JSON file you downloaded earlier to:

• Linux/macOS: ~/.config/google-workspace-mcp/credentials.json

• Windows: %USERPROFILE%\.config\google-workspace-mcp\credentials.json

Or override the location using the GOOGLE_WORKSPACE_MCP_CREDENTIALS environment variable.

4. First-Time Authentication

When a tool is called for the first time and no token is stored yet, the server will open your browser for Google's consent flow automatically. You can also trigger this manually ahead of time (before using in your MCP client) so the browser opens before you need it:

source venv/bin/activate
python3 -c "from google_workspace_mcp.auth import drive_service; drive_service(); print('OK, token saved.')"

The consent token is saved to ~/.config/google-workspace-mcp/token.json and will refresh automatically as long as it remains valid.

5. Configure Your MCP Client

Register this server with your MCP client following its configuration guidelines.

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry (adjust the path to your project location):

{
  "mcpServers": {
    "google-workspace": {
      "command": "/absolute/path/to/google_workspace_mcp/venv/bin/python",
      "args": ["-m", "google_workspace_mcp.server"]
    }
  }
}

On Windows, use the Windows venv path:

{
  "mcpServers": {
    "google-workspace": {
      "command": "C:\\absolute\\path\\to\\google_workspace_mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "google_workspace_mcp.server"]
    }
  }
}

If using Option A (client ID/secret via env, without credentials.json file), add an env block:

{
  "mcpServers": {
    "google-workspace": {
      "command": "C:\\absolute\\path\\to\\google_workspace_mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "google_workspace_mcp.server"],
      "env": {
        "GOOGLE_WORKSPACE_MCP_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "GOOGLE_WORKSPACE_MCP_CLIENT_SECRET": "GOCSPX-xxxxx"
      }
    }
  }
}

After saving the config, restart your MCP client. The tools above will be available to use.

Other MCP Clients

Refer to your client's documentation for how to register custom MCP servers. The server runs on stdio and expects the Python command and arguments shown above.

Project Structure

google_workspace_mcp/
├── pyproject.toml
├── requirements.txt
├── README.md
└── src/google_workspace_mcp/
    ├── server.py       # entry point, registers all tools
    ├── auth.py         # OAuth2 flow + service client cache
    ├── formatting.py   # helper for JSON output & error handling
    └── tools/
        ├── drive.py
        ├── sheets.py
        ├── docs.py
        ├── calendar.py
        └── gmail.py

Security & Limitations

• Tokens are stored locally in ~/.config/google-workspace-mcp/token.json with 600 permissions (Linux/macOS). Never commit this file or credentials.json to git.

• drive_trash_file moves files to trash (can be recovered), it does not permanently delete.

• gmail_send_message and calendar_create_event (with attendees) execute real actions immediately (email sent / invitation sent) without a separate confirmation button at the API level — make sure you've verified the content/recipient before calling these tools.

• The requested scopes are fairly broad (drive, not drive.file) so you can access files created outside this app. If you want to restrict access only to files created/opened through this app, change the Drive scope in auth.py to drive.file and delete the old token to re-consent.

Adding New Tools

Follow the same pattern in the tools/*.py modules: define a Pydantic input model, then register it via @mcp.tool(name=..., annotations={...}) inside the register(mcp) function. Use handle_google_api_error() from formatting.py for consistent error handling.

License

MIT

Creator

This MCP was created by and is maintained by Heru Arief Wijaya.

• https://twitter.com/hoaaah

• https://github.com/hoaaah