# Google Workspace MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with Google Workspace — specifically **Gmail** (draft emails) and **Google Docs** (append content).

## Primary Use Case: Review Analysis Pipeline

An AI agent collects product reviews, normalizes ratings to a 5-point scale, performs sentiment analysis, and uses this MCP server to:
- **Append** the full analysis report to a Google Doc
- **Draft** a summary notification email via Gmail

## Quick Start

### Prerequisites
- Node.js 18+ installed
- A Google Cloud project with Gmail API and Google Docs API enabled
- OAuth 2.0 Client ID credentials (Desktop application type)

### 1. Clone & Install
```bash
git clone https://github.com/<your-username>/google-workspace-mcp.git
cd google-workspace-mcp
npm install
```

### 2. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` and add your Google OAuth credentials:
```
GOOGLE_CLIENT_ID="your-client-id-here"
GOOGLE_CLIENT_SECRET="your-client-secret-here"
```

### 3. Build
```bash
npm run build
```

### 4. Run Locally (Stdio — for local MCP clients)
```bash
npm start
```
On first run, the server will print an authorization URL. Open it in your browser, sign in with your Google account, and grant the requested permissions. A `token.json` file will be created automatically.

### 5. Run as HTTP Server (for Railway / remote deployment)
```bash
npm run start:http
```
This starts an Express server with Streamable HTTP transport on port 3000.

## Connect to an MCP Client

### Claude Desktop (Local — Stdio)
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["<path-to-project>/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Claude Desktop (Remote — Railway)
```json
{
  "mcpServers": {
    "google-workspace": {
      "url": "https://<your-app>.up.railway.app/mcp",
      "transport": "streamable-http"
    }
  }
}
```

## Available Tools

| Tool | Description | Arguments |
|------|-------------|-----------|
| `gmail_create_draft` | Create a draft email in Gmail | `to`, `subject`, `body` |
| `google_docs_append` | Append text to a Google Document | `documentId`, `content` |

## Deploy to Railway

1. Push this repo to GitHub
2. Go to [railway.app](https://railway.app/) → **New Project** → **Deploy from GitHub Repo**
3. Set environment variables in Railway dashboard:
   - `GOOGLE_CLIENT_ID`
   - `GOOGLE_CLIENT_SECRET`
   - `GOOGLE_OAUTH_TOKEN` (paste contents of your local `token.json`)
4. Railway will auto-build and deploy using `railway.json` config

See [deploymentplan.md](./deploymentplan.md) for detailed deployment instructions.

## Google Cloud Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select existing)
3. Enable **Gmail API** and **Google Docs API**
4. Go to **Credentials** → **Create Credentials** → **OAuth Client ID**
5. Application type: **Desktop application**
6. Download the credentials and copy `Client ID` and `Client Secret` to `.env`
7. Configure the **OAuth consent screen** (add test users if in testing mode)

## Project Structure

```
google-workspace-mcp/
├── src/
│   ├── index.ts       # MCP server entry point (Stdio transport — local)
│   ├── server.ts      # MCP server entry point (HTTP transport — Railway)
│   ├── auth.ts        # OAuth 2.0 authentication & token caching
│   ├── gmail.ts       # Gmail draft creation
│   └── docs.ts        # Google Docs content appending
├── .env.example       # Environment variable template
├── railway.json       # Railway deployment configuration
├── package.json       # Dependencies & scripts
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file
```

## Security Notes

- **Tokens are local**: `token.json` is stored locally and never committed
- **Drafts only**: Emails are saved as drafts — the user must manually send
- **Scoped access**: Only requests `gmail.compose` and `documents` scopes
- **No data sent to AI**: All auth is handled server-side

## License

ISC