# google-cli-mcp

An MCP (Model Context Protocol) server that exposes Google Workspace APIs as tools for AI assistants like Claude, Cursor, and others. It uses Google's Discovery API to auto-generate tools at runtime — no manual tool definitions required.

> Built with [Claude Code](https://claude.ai/code) by Anthropic.

---

## What it does

Connects your AI assistant to 17 Google Workspace services:

| Alias | Service |
|---|---|
| `drive` | Google Drive |
| `sheets` | Google Sheets |
| `gmail` | Gmail |
| `calendar` | Google Calendar |
| `docs` | Google Docs |
| `slides` | Google Slides |
| `tasks` | Google Tasks |
| `people` | Google People / Contacts |
| `chat` | Google Chat |
| `classroom` | Google Classroom |
| `forms` | Google Forms |
| `keep` | Google Keep |
| `meet` | Google Meet |
| `admin-directory` | Admin SDK - Directory |
| `admin-reports` | Admin SDK - Reports |
| `events` | Workspace Events |
| `modelarmor` | Model Armor |

---

## Requirements

- **Node.js >= 18**
- A Google account with access to the services you want to use
- Google credentials (see [Authentication](#authentication) below)

`gcloud` CLI is **not required** — but it is one of the two supported auth methods.

---

## Installation

```bash
git clone https://github.com/ChrisNoronha/google-cli-mcp.git
cd google-cli-mcp
npm install
npm run build
```

---

## Authentication

The server supports two credential methods. Use whichever fits your setup.

### Option 1: Bearer token (no gcloud needed)

Set the `GOOGLE_WORKSPACE_CLI_TOKEN` environment variable to a valid Google OAuth 2.0 bearer token:

```bash
export GOOGLE_WORKSPACE_CLI_TOKEN="ya29.your-token-here"
```

**Note:** Bearer tokens expire (typically after 1 hour) and must be rotated manually. This option is best for quick testing or short-lived automation.

### Option 2: Application Default Credentials (ADC)

This method uses `gcloud` to authenticate once and handles token refresh automatically — recommended for long-running use.

```bash
# Install gcloud CLI if you haven't already
# https://cloud.google.com/sdk/docs/install

gcloud auth application-default login
```

After logging in, the server will pick up your credentials automatically.

---

## Configuration

All configuration is done via environment variables.

| Variable | Default | Description |
|---|---|---|
| `GOOGLE_WORKSPACE_CLI_TOKEN` | — | Bearer token (Option 1 auth) |
| `GWS_MCP_SERVICES` | all services | Comma-separated list of service aliases to load (e.g. `gmail,drive,calendar`) |
| `GWS_MCP_SCOPES` | all scopes | Space-separated OAuth scopes (only used with ADC auth) |

### Load only specific services

```bash
export GWS_MCP_SERVICES="gmail,drive,calendar"
```

Leave `GWS_MCP_SERVICES` unset to load all 17 services.

---

## Usage

### Run the server

```bash
# Development (no build step)
npm run dev

# Production (after npm run build)
node dist/index.js
```

### Connect to Claude Desktop

Add this to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-cli-mcp/dist/index.js"],
      "env": {
        "GWS_MCP_SERVICES": "gmail,drive,calendar"
      }
    }
  }
}
```

### Connect to Claude Code

```bash
claude mcp add google-workspace -- node /path/to/google-cli-mcp/dist/index.js
```

---

## Development

```bash
npm run dev      # run with tsx (no build)
npm run build    # compile TypeScript to dist/
npm test         # run tests
npm run test:watch  # watch mode
```

---

## How it works

1. **Auth** — resolves credentials from env var or ADC
2. **Discovery** — fetches Google API Discovery Documents in parallel (10s timeout per service)
3. **Tool generation** — builds MCP tool definitions from the Discovery Documents automatically
4. **Server** — starts a stdio MCP server and registers all tools
5. **Dispatch** — each tool call is proxied to the corresponding Google REST API with the resolved auth token

---

## License

MIT

---

*Created with [Claude Code](https://claude.ai/code)*