gscope

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 (one-time, ~5 min)
2. Install gscope
3. Add to Claude Code
4. 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
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

1. Click Save

1. Go to "Audience" (or "Público-alvo")
2. Make sure it says "Testing" (not "In production")

• If it says "In production", click "Back to testing" / "Voltar para o teste"

1. Under "Test users", click "Add users"
2. Add the email of the Google account you'll use (the one you'll sign in with)
3. 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

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

Add to Claude Code

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

Or add manually to your MCP config:

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

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

{
  "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