# gworkspace-mcp

Model Context Protocol server for Google Workspace automation: Google Sheets, Apps Script, Drive, Docs, Gmail, and triggers. Built with [FastMCP](https://github.com/jlowin/fastmcp).

Designed to be used from Claude Code (or any MCP-compatible client) so you can edit Apps Script projects, manipulate spreadsheets, send emails and manage Drive files directly from a conversation.

## Features

- **Apps Script** (9 tools) — list, read, update, create, deploy and run Apps Script projects. Granular file edits so you don't have to rewrite entire scripts.
- **Sheets** (10 tools) — read/write ranges, batch updates, formatting, protection, formulas, dashboards.
- **Drive** (4 tools) — list, search, move and manage files.
- **Docs** (1 tool) — read/edit Google Docs.
- **Gmail** (3 tools) — compose and send email.
- **Triggers** (3 tools) — manage Apps Script time-based and event triggers.
- **Connect** (1 tool) — bind a local Apps Script project to a spreadsheet.

## Requirements

- Python 3.10+
- A Google Cloud project with the following APIs enabled:
  - Google Sheets API
  - Google Drive API
  - Apps Script API
  - Google Docs API
  - Gmail API
  - Google Calendar API
- OAuth 2.0 Desktop credentials (`client_secret.json`)

## Installation

```bash
git clone https://github.com/LeooNic/gworkspace-mcp.git
cd gworkspace-mcp
pip install -e .
```

Or with `uv`:

```bash
uv pip install -e .
```

## Google Cloud setup

1. Go to [console.cloud.google.com](https://console.cloud.google.com/) and create a project.
2. Enable the APIs listed above under **APIs & Services → Library**.
3. Go to **APIs & Services → OAuth consent screen**, configure it as **External**, and add your Google account as a test user.
4. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**, choose **Desktop app**, and download the JSON.
5. Make the credentials available to the server in one of these ways:
   - Place the JSON at `~/.secrets/gworkspace-mcp/client_secret.json`, or
   - Set `GOOGLE_CLIENT_SECRET_PATH=/full/path/to/client_secret.json`, or
   - Set `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` as env vars.

The first time a tool runs, a browser window will open for OAuth consent. The resulting token is stored at `~/.secrets/gworkspace-mcp/token.json` and refreshed automatically.

## Register with Claude Code

Add this to your Claude Code `settings.json` (or `~/.claude.json`):

```json
{
  "mcpServers": {
    "gworkspace": {
      "command": "gworkspace-mcp"
    }
  }
}
```

If `gworkspace-mcp` is not on your PATH, use the absolute path to the executable created by `pip install -e .` (on Windows, typically `C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\Scripts\gworkspace-mcp.exe`).

Alternative invocation without installing the entry point:

```json
{
  "mcpServers": {
    "gworkspace": {
      "command": "python",
      "args": ["-m", "gworkspace_mcp.server"]
    }
  }
}
```

## OAuth scopes

The server requests the following scopes:

- `spreadsheets`, `drive`, `documents`, `calendar`
- `script.projects`, `script.deployments`, `script.processes`, `script.metrics`
- `gmail.send`, `gmail.compose`
- `userinfo.email`, `userinfo.profile`

## Security notes

- Your `client_secret.json` and `token.json` are personal — never commit them. The repo `.gitignore` already excludes them.
- Tokens live under `~/.secrets/gworkspace-mcp/`.
- The server runs locally; it does not expose any network endpoint.

## License

MIT — see [LICENSE](LICENSE).