# Google Tools MCP Server (`google-tools-mcp-server`)

A Model Context Protocol (MCP) server that connects AI agent environments (such as **Cursor**, **AntiGravity**, **Windsurf**, and **Claude Desktop**) to Google Workspace services—specifically **Gmail** and **Google Docs**.

---

## Features & Tools

The server registers 4 tools over standard MCP JSON-RPC:

| Tool | Description | Input Parameters |
| :--- | :--- | :--- |
| `gmail_send_email` | Sends an email directly via the authenticated Gmail account. | `to` (required), `subject` (required), `body_text`, `body_html`, `cc`, `bcc`, `reply_to` |
| `gmail_create_draft` | Creates a draft in Gmail for user review before sending. | `to`, `subject`, `body_text`, `body_html`, `cc`, `bcc` |
| `gdocs_append_content` | Appends formatted or plain text to an existing Google Document. | `document_id` (required), `text_content` (required), `insert_line_break` (boolean), `formatting` (`PLAIN_TEXT`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `BULLET_LIST`) |
| `gdocs_get_document_info` | Retrieves document title, character count, and revision ID. | `document_id` (required) |

---

## 1. Setup Google Cloud Credentials

To allow the MCP server to communicate with Gmail and Google Docs:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create or select a Google Cloud Project.
3. Enable the following APIs in **APIs & Services > Library**:
   - **Gmail API**
   - **Google Docs API**
   - **Google Drive API**
4. Configure your **OAuth Consent Screen** (**APIs & Services > OAuth consent screen**):
   - Choose User Type: **External** (or Internal for Google Workspace domain).
   - Add the scopes:
     - `https://www.googleapis.com/auth/gmail.send`
     - `https://www.googleapis.com/auth/gmail.compose`
     - `https://www.googleapis.com/auth/documents`
     - `https://www.googleapis.com/auth/drive.readonly`
   - Add your own email as a **Test User**.
5. Create OAuth Credentials (**APIs & Services > Credentials**):
   - Click **Create Credentials > OAuth client ID**.
   - Application Type: **Web application**.
   - Name: `google-tools-mcp-server`.
   - Authorized redirect URIs: Add `http://localhost:3000/oauth2callback`.
   - Click **Create** and copy your **Client ID** and **Client Secret**.

---

## 2. Installation & Token Generation

### Step A: Clone & Install Dependencies
```bash
npm install
```

### Step B: Configure Environment Variables
Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
Fill in your credentials:
```env
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
```

### Step C: Generate Refresh Token
Run the interactive helper script:
```bash
npm run auth:token
```
1. Open the URL shown in your browser.
2. Sign in and grant the requested permissions.
3. Copy the output `GOOGLE_REFRESH_TOKEN` into your `.env` file.

### Step D: Build the Server
```bash
npm run build
```

---

## 3. Host Integration

### AntiGravity / Cursor Integration
Add the server definition to your `mcp_config.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "google-tools": {
      "command": "node",
      "args": ["/absolute/path/to/google-tools-mcp-server/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### Claude Desktop Integration
Add the following to your `claude_desktop_config.json`:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-tools": {
      "command": "node",
      "args": ["/absolute/path/to/google-tools-mcp-server/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

---

## 4. Testing with MCP Inspector

You can test and inspect tool calls locally using the official `@modelcontextprotocol/inspector`:

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

---

## 5. Security & Architectural Invariants

- **Stdio Isolation:** All logging, debug outputs, and errors are written exclusively to `process.stderr`. `process.stdout` is strictly reserved for JSON-RPC 2.0 protocol packets.
- **Automatic Token Refresh:** The server automatically refreshes OAuth access tokens in the background when they expire without terminating the connection.
- **Safe Error Recovery:** All tool invocations are wrapped in defensive boundaries; malformed requests or API errors return structured MCP error responses (`isError: true`) instead of crashing the server process.