# gscope - Google Workspace MCP Server

MCP server that lets AI assistants (like Claude Code) work with Google Docs, Sheets, and Drive using your own Google account.

## Quick Start

1. [Set up Google Cloud credentials](#google-cloud-setup) (one-time, ~5 min)
2. [Install gscope](#installation)
3. [Add to Claude Code](#add-to-claude-code)
4. [Authenticate](#authenticate)

---

## Google Cloud Setup

You need to create OAuth credentials in Google Cloud Console so gscope can access Google APIs on your behalf. This is a one-time setup.

### 1. Create or select a Google Cloud project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click the project dropdown at the top of the page
3. Click **"New Project"**
4. Name it anything (e.g., `gscope`) and click **Create**
5. Make sure the new project is selected in the dropdown

### 2. Enable the Google APIs

1. In the left sidebar, go to **"APIs & Services"** > **"Library"**
2. Search for and enable each of these (click on each one, then click **"Enable"**):
   - **Google Docs API**
   - **Google Sheets API**
   - **Google Drive API**

### 3. Configure the OAuth consent screen

> **This step is required before creating credentials. Skipping it will cause errors.**

1. In the left sidebar, go to **"Google Auth Platform"** > **"Branding"** (or **"APIs & Services"** > **"OAuth consent screen"**)
2. Fill in the required fields:
   - **App name**: `gscope` (or any name you like)
   - **User support email**: select your email
   - **Developer contact email**: your email
3. Click **Save**

4. Go to **"Audience"** (or **"Público-alvo"**)
5. Make sure it says **"Testing"** (not "In production")
   - If it says "In production", click **"Back to testing"** / **"Voltar para o teste"**
6. Under **"Test users"**, click **"Add users"**
7. **Add the email of the Google account you'll use** (the one you'll sign in with)
8. Click **Save**

> **Important**: While your app is in "Testing" mode, only the emails you add as test users can sign in. This is normal and expected for personal use.

### 4. Create OAuth credentials

1. In the left sidebar, go to **"Credentials"** (or **"Clientes"**)
2. Click **"Create Credentials"** > **"OAuth client ID"**
3. Application type: **Desktop app**
4. Name: `gscope` (or anything)
5. Click **Create**
6. A dialog will show your **Client ID** and **Client Secret**
7. **Copy both values** — you'll need them in the next step

Your Client ID looks like: `123456789-xxxxxxxxxx.apps.googleusercontent.com`
Your Client Secret looks like: `GOCSPX-xxxxxxxxxxxxxxxxx`

### 5. Summary

After completing these steps you should have:
- A Google Cloud project with Docs, Sheets, and Drive APIs enabled
- An OAuth consent screen configured in Testing mode with your email as test user
- A Desktop OAuth client with a Client ID and Client Secret

---

## Installation

```bash
git clone https://github.com/MatheusKindrazki/gscope.git
cd gscope
npm install
npm run build
```

## Add to Claude Code

```bash
claude mcp add --scope user gscope -- node /full/path/to/gscope/dist/index.js
```

Or add manually to your MCP config:

```json
{
  "mcpServers": {
    "gscope": {
      "command": "node",
      "args": ["/full/path/to/gscope/dist/index.js"]
    }
  }
}
```

Then restart Claude Code.

## Authenticate

In Claude Code, set up your credentials (only need to do this once):

```
Use google_workspace_setup with clientId "YOUR_CLIENT_ID" and clientSecret "YOUR_CLIENT_SECRET"
```

Then sign in with Google:

```
Use google_workspace_login
```

A browser window will open. Sign in with the Google account you added as a test user. After approving, you're done!

---

## What can it do?

### Google Docs (6 tools)
| Tool | Description |
|------|-------------|
| `google_docs_create` | Create a new document |
| `google_docs_get` | Read document content and metadata |
| `google_docs_append_text` | Append text to end of document |
| `google_docs_replace_text` | Find and replace text |
| `google_docs_insert_markdown_as_text` | Insert markdown as formatted text |
| `google_docs_batch_update` | Raw batch update (advanced) |

### Google Sheets (6 tools)
| Tool | Description |
|------|-------------|
| `google_sheets_create` | Create a new spreadsheet |
| `google_sheets_get` | Read spreadsheet metadata and values |
| `google_sheets_write_values` | Write values to a range |
| `google_sheets_append_values` | Append rows to a sheet |
| `google_sheets_clear_range` | Clear values from a range |
| `google_sheets_batch_update` | Raw batch update (advanced) |

### Google Drive (5 tools)
| Tool | Description |
|------|-------------|
| `google_drive_list_files` | List and search files |
| `google_drive_get_file` | Get file metadata |
| `google_drive_move_file` | Move file to another folder |
| `google_drive_create_folder` | Create a folder |
| `google_drive_share_file` | Share with another user |

### Management (6 tools)
| Tool | Description |
|------|-------------|
| `google_workspace_setup` | Create config file (run this first!) |
| `google_workspace_login` | Sign in with Google (opens browser) |
| `google_workspace_logout` | Sign out and revoke tokens |
| `google_workspace_current_scope` | Show active config and auth status |
| `google_workspace_list_scopes` | List all configured accounts |
| `google_workspace_validate_config` | Check if everything is set up correctly |

---

## Configuration

### Minimal config (recommended)

Only two values are required — everything else is auto-configured:

```json
{
  "google": {
    "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }
}
```

**Auto-configured defaults:**
- **Google Scopes**: Docs + Sheets + Drive (read/write)
- **OAuth Port**: Automatically finds a free port
- **Token Storage**: `~/.config/google-mcp/<scope-name>.tokens.json`

### Multiple Google accounts

Use a global config at `~/.config/google-mcp/config.json`:

```json
{
  "defaultScope": "personal",
  "scopes": {
    "personal": {
      "google": {
        "clientId": "PERSONAL_CLIENT_ID",
        "clientSecret": "PERSONAL_SECRET"
      }
    },
    "work": {
      "google": {
        "clientId": "WORK_CLIENT_ID",
        "clientSecret": "WORK_SECRET"
      }
    }
  }
}
```

Use `scopeName: "work"` in any tool call to switch accounts.

### Per-project config

Create `.google-mcp.json` in any project directory. gscope detects it automatically.

### Config resolution order

1. `.google-mcp.local.json` in current directory
2. `.google-mcp.json` in current directory
3. Same files in parent directories (up to git root)
4. Global config at `~/.config/google-mcp/config.json`

---

## Troubleshooting

### Google OAuth errors

**Error 500 on Google sign-in page**
- Make sure the OAuth consent screen is configured (app name, emails filled in)
- Make sure the app is in **"Testing"** mode (not "In production")
- Make sure your email is added as a **test user**
- Wait a few minutes after making changes — Google can take time to propagate

**Error 403: access_denied**
- Your email is not in the test users list
- Go to Google Cloud Console > OAuth consent screen > Test users > Add your email

**Error: redirect_uri_mismatch**
- For Desktop apps, this should not happen. If it does, make sure your OAuth client type is "Desktop app" (not "Web application")

### gscope errors

**"No Google Workspace configuration found"**
- Run `google_workspace_setup` with your Client ID and Secret
- Or create a config file manually (see Configuration above)

**"Not authenticated"**
- Run `google_workspace_login` — a browser will open for Google sign-in

**"Missing required Google API scopes"**
- Remove the `scopes` field from your config to use defaults (Docs + Sheets + Drive)

**Browser didn't open for login**
- Copy the URL shown in the output and paste it into your browser manually

**MCP not showing in Claude Code**
- Make sure you ran `npm run build` after cloning
- Make sure the path in your MCP config points to `dist/index.js` (not `src/index.ts`)
- Restart Claude Code completely (close and reopen, not just /clear)
- Run `claude mcp list` to verify the server is connected

---

## Advanced

See `examples/advanced-global-config.json` for:
- Custom OAuth redirect ports
- Custom Google API scopes
- Aliases for scope names
- Per-scope default Drive folders
- Document locale settings

## Architecture

```
src/
├── index.ts              # Entry point (stdio transport)
├── server/server.ts      # McpServer setup, tool registration
├── config/               # Hierarchical scope resolution
│   ├── schema.ts         # Zod schemas for config validation
│   ├── loader.ts         # Config file reading and merging
│   └── resolver.ts       # ScopeResolver (finds the right config)
├── auth/                 # OAuth 2.0 authentication
│   ├── oauth.ts          # Login flow with local HTTP callback
│   └── token-store.ts    # Token persistence per scope
├── google/               # Google API operations
│   ├── client.ts         # Client factory with caching
│   ├── docs.ts           # Google Docs operations
│   ├── sheets.ts         # Google Sheets operations
│   └── drive.ts          # Google Drive operations
├── tools/                # MCP tool definitions
│   ├── common.ts         # Shared params and helpers
│   ├── docs.ts           # 6 Docs tools
│   ├── sheets.ts         # 6 Sheets tools
│   ├── drive.ts          # 5 Drive tools
│   └── workspace.ts      # 6 management tools
└── utils/
    ├── logger.ts         # Structured logging (stderr, secrets masked)
    ├── git.ts            # Git root detection
    └── port.ts           # Auto free port detection
```

## Security

- Tokens stored locally per-scope (never shared between accounts)
- Secrets never appear in logs (masked with `***REDACTED***`)
- Token data never included in tool responses
- Uses `drive.file` scope by default (minimal permissions)
- All logs go to stderr (stdout reserved for MCP protocol)

## License

MIT