# onit-workspace

Google Workspace MCP Server over SSE. Provides 25 tools for Google Drive, Docs, Sheets, Slides, and Gmail.

Vendored from [onit](https://github.com/sibyl-oracles/onit).

## Installation

```bash
pip install onit-workspace
```

## Usage

Start the server (runs in background):
```bash
onit-workspace
# or
onit-workspace start
```

Start in foreground (for debugging):
```bash
onit-workspace start --foreground
```

Custom host/port:
```bash
onit-workspace start --host 127.0.0.1 --port 9000
```

With OAuth 2.0 (recommended):
```bash
onit-workspace start --oauth-client-file /path/to/client_secret.json
```

With service account credentials:
```bash
onit-workspace start --credentials-file ~/.config/gcloud/credentials.json
```

With domain-wide delegation (service account + Gmail):
```bash
onit-workspace start --delegated-user user@yourcompany.com
```

Check status:
```bash
onit-workspace status
```

Stop the server:
```bash
onit-workspace stop
```

## Using with onit

[onit](https://github.com/sibyl-oracles/onit) can connect to onit-workspace as an MCP SSE server. Start onit-workspace first, then launch onit with the `--mcp-sse` flag:

```bash
onit-workspace start
onit --mcp-sse http://localhost:18204/sse --web
```

This gives onit access to all 25 Google Workspace tools through its web interface.

### Example prompts

Once connected, you can ask onit things like:

```
"List files in my Google Drive"
"Create a new spreadsheet called Q1 Report with columns Date, Revenue, Expenses"
"Read the contents of document <doc_id>"
"Send an email to team@company.com with subject 'Meeting Notes'"
"Download the presentation as PDF"
"Share the document with user@company.com as editor"
```

## MCP Client Configuration

Once running, connect any MCP client to the SSE endpoint:

```
http://localhost:18204/sse
```

Example MCP client config:

```json
{
  "mcpServers": {
    "onit-workspace": {
      "url": "http://localhost:18204/sse"
    }
  }
}
```

## Authentication

Two authentication methods are supported. Choose the one that fits your environment.

### Option 1: OAuth 2.0 (recommended)

User-based authentication via browser login. Works without domain-wide delegation — ideal when delegation is disabled for security reasons.

1. Go to [Google Cloud Console](https://console.cloud.google.com/) > APIs & Services > Credentials
2. Enable APIs: Docs, Sheets, Slides, Drive, Gmail
3. Create an **OAuth 2.0 Client ID** (type: **Desktop application**)
4. Download the client secrets JSON
5. Start the server:

```bash
onit-workspace start --oauth-client-file /path/to/client_secret.json
```

Or set the environment variable:
```bash
export GOOGLE_OAUTH_CLIENT_FILE=/path/to/client_secret.json
onit-workspace start
```

On first API call, a browser opens for Google login. The token is saved to `~/.config/gcloud/token.pickle` for subsequent runs.

### Option 2: Service account

Server-to-server authentication using a service account key.

1. Create a service account at [Google Cloud Console](https://console.cloud.google.com/) > IAM & Admin > Service Accounts
2. Enable APIs: Docs, Sheets, Slides, Drive, Gmail
3. Download JSON key and configure via one of:
   - CLI flag: `--credentials-file /path/to/service-account.json`
   - Environment variable: `GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json`
   - Default path: `~/.config/gcloud/credentials.json`
4. Share existing files with the service account email

**Gmail with service account** requires domain-wide delegation:

1. Enable delegation on the service account in Google Cloud Console
2. Authorize scopes in [Google Admin Console](https://admin.google.com/) > Security > API Controls > Domain-wide delegation
3. Pass `--delegated-user user@yourcompany.com` or use the `user_email` parameter per tool call

See [docs/GOOGLE_WORKSPACE_AND_OAUTH.md](docs/GOOGLE_WORKSPACE_AND_OAUTH.md) for the full setup guide.

## Tools (25)

| Category | Tools | Description |
|----------|-------|-------------|
| Auth | `google_auth` | Check authentication status |
| Drive | `drive_list`, `drive_create_folder`, `drive_move`, `drive_delete`, `drive_share`, `drive_download`, `drive_upload` | Search, organize, share, upload, and download files |
| Docs | `doc_create`, `doc_read`, `doc_write`, `doc_update` | Full CRUD for Google Docs |
| Sheets | `sheet_create`, `sheet_read`, `sheet_write`, `sheet_info` | Full CRUD for Google Sheets |
| Slides | `slides_create`, `slides_read`, `slides_edit`, `slides_update` | Full CRUD for Google Slides |
| Gmail | `gmail_list`, `gmail_read`, `gmail_modify`, `gmail_send`, `gmail_attachment`, `gmail_create_label` | Read, send, label, and manage email |

**Drive (7 tools):**
- `drive_list` - Search and list files with filtering by type, folder, and query
- `drive_create_folder` - Create folders with optional auto-sharing
- `drive_move` - Move or rename files and folders
- `drive_delete` - Trash or permanently delete files
- `drive_share` - Share with users, groups, domains, or make public
- `drive_download` - Download/export files (PDF, DOCX, XLSX, PPTX, etc.)
- `drive_upload` - Upload local files to Drive with optional sharing

**Docs (4 tools):**
- `doc_create` - Create a new Google Doc with optional initial content
- `doc_read` - Read document content as plain text or JSON structure
- `doc_write` - Append, insert, or replace content (text, headings, bullets, numbered lists, tables)
- `doc_update` - Modify or delete existing paragraphs by index, change paragraph styles

**Sheets (4 tools):**
- `sheet_create` - Create a new spreadsheet with optional headers and data
- `sheet_read` - Read data from a cell range
- `sheet_write` - Update or append rows of data
- `sheet_info` - Get spreadsheet metadata (sheet names, dimensions, frozen rows/columns)

**Slides (4 tools):**
- `slides_create` - Create a new presentation with title and subtitle
- `slides_read` - Read full slide content including shapes, tables, and speaker notes
- `slides_edit` - Add new slides (multiple layouts) or tables
- `slides_update` - Modify existing shape text or delete slides

**Gmail (6 tools):**
- `gmail_list` - List and search emails with query filters
- `gmail_read` - Read full email with headers, body, and attachment info
- `gmail_modify` - Modify labels, read/unread status, and star
- `gmail_send` - Compose and send email with optional attachments and HTML
- `gmail_attachment` - List or download email attachments
- `gmail_create_label` - Create labels or apply labels to messages

## Docker

See [docs/DOCKER.md](docs/DOCKER.md) for Docker build and run instructions.

## Documentation

- [Docker](docs/DOCKER.md) — build, run, and Docker Compose setup
- [Google Workspace & OAuth Setup](docs/GOOGLE_WORKSPACE_AND_OAUTH.md) — full setup guide
- [OAuth Quick Start](docs/OAUTH_SETUP_QUICK_START.md) — 5-minute OAuth setup checklist
- [OAuth Redirect Flow](docs/OAUTH_REDIRECT_FLOW.md) — detailed OAuth2 implementation

## License

Apache-2.0
