# Google Services MCP Server

A Model Context Protocol (MCP) server that exposes Google services — specifically Gmail and Google Docs — as standardized tools for AI agents.

This allows MCP-compatible agents (like Claude Desktop, Cursor, or custom agents) to seamlessly send/draft emails and append content to Google Docs on your behalf.

---

## Capabilities (Tools)

| Tool | Description |
|------|-------------|
| `gmail_send_email` | Send an email to one or more recipients with subject, body (text/html), and optional CC/BCC. |
| `gmail_draft_email` | Create a draft email in your Gmail account without sending it. |
| `gdocs_append_content` | Append text content to the end of an existing Google Doc, with optional formatting (heading level, bold, italic). |

---

## Prerequisites

1. **Node.js**: Version 20 or higher.
2. **Google Cloud Project**: You need to set up a project and obtain OAuth 2.0 credentials.

---

## 🛠️ Google Cloud Setup Guide

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. **Create a new project** (e.g., "MCP Server").
3. Go to **APIs & Services > Library**.
   - Search for and enable the **Gmail API**.
   - Search for and enable the **Google Docs API**.
4. Go to **APIs & Services > OAuth consent screen**.
   - Choose **External** (or Internal if you have a Workspace).
   - Fill out the App Name, User support email, and Developer contact information.
   - Click **Save and Continue**.
   - Under Scopes, add:
     - `https://www.googleapis.com/auth/gmail.send`
     - `https://www.googleapis.com/auth/gmail.compose`
     - `https://www.googleapis.com/auth/documents`
   - Finish the consent screen setup.
5. Go to **APIs & Services > Credentials**.
   - Click **Create Credentials > OAuth client ID**.
   - Application type: **Web application**.
   - Name: "MCP Server Local".
   - Under **Authorized redirect URIs**, add exactly: `http://localhost:3000/oauth2callback`
   - Click **Create**.
   - Note down your **Client ID** and **Client Secret**.

---

## 🚀 Installation & Authentication

1. Clone or copy this repository.
2. Install dependencies:
   ```bash
   npm install
   ```
3. Copy the environment template:
   ```bash
   cp .env.example .env
   ```
4. Open `.env` and fill in your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.
5. Run the authentication script to obtain your refresh token:
   ```bash
   npm run authenticate
   ```
6. Follow the prompt in your browser to authorize the app. Once completed, the terminal will output a `GOOGLE_REFRESH_TOKEN`.
7. Add the `GOOGLE_REFRESH_TOKEN` to your `.env` file.
8. Build the server:
   ```bash
   npm run build
   ```

---

## 🔌 Connecting to an MCP Client

### Claude Desktop
Add the following to your `claude_desktop_config.json` (usually found at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "google-services": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-mcp-server/build/index.js"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_REDIRECT_URL": "http://localhost:3000/oauth2callback"
      }
    }
  }
}
```

*Note: Replace `/absolute/path/to/` with the actual path to this folder.*

---

## 🔧 Architecture

This server is built using the **MCP SDK v2**. It uses the `stdio` transport to communicate with the host agent. 
The architecture is designed to be highly modular. Adding a new Google service requires:
1. Creating a new folder in `src/tools/`.
2. Defining Zod schemas for inputs.
3. Implementing the Google API logic.
4. Calling the registration function in `src/tools/index.ts`.

It includes built-in exponential backoff for rate limiting and structured error handling for a robust agent experience.

---

## ⚠️ Troubleshooting

- **Authentication Error / Missing Token**: Make sure you ran `npm run authenticate` and copied the refresh token into your `.env` file or Claude config.
- **Permission Denied (403)**: Ensure you added all 3 required scopes during the Google Cloud OAuth consent screen setup, and that the account you authenticated with has access to the target Google Doc.
- **Resource Not Found (404)**: Double check the `document_id`. It should be the string between `/d/` and `/edit` in the Google Docs URL.