# google-workspace-mcp

[![Verified by M8ven](https://m8ven.ai/badge/mcp/hoaaah-google-workspace-mcp-server-ky9x9n)](https://m8ven.ai/verified?check=https%3A%2F%2Fgithub.com%2Fhoaaah%2Fgoogle-workspace-mcp-server)

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

| Service  | Tools |
|----------|-------|
| Drive    | `drive_search_files`, `drive_get_file_metadata`, `drive_read_file_content`, `drive_upload_file`, `drive_create_folder`, `drive_download_file`, `drive_trash_file` |
| Sheets   | `sheets_read_range`, `sheets_write_range`, `sheets_append_values`, `sheets_clear_range`, `sheets_create_spreadsheet`, `sheets_list_tabs` |
| Docs     | `docs_create_document`, `docs_read_document`, `docs_append_text`, `docs_replace_text` |
| Calendar | `calendar_list_calendars`, `calendar_list_events`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event` |
| Gmail    | `gmail_search_messages`, `gmail_get_message`, `gmail_send_message`, `gmail_create_draft`, `gmail_list_labels` |

## 1. Setup Google Cloud Project

1. Open [Google Cloud Console](https://console.cloud.google.com/) 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

```bash
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:

```bash
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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](LICENSE)


# Creator

This MCP was created by and is maintained by **[Heru Arief Wijaya](http://belajararief.com/)**.

* https://twitter.com/hoaaah
* https://github.com/hoaaah