# Google Workspace MCP Server (Gmail + Google Docs)

A Model Context Protocol (MCP) server that exposes Google Workspace capabilities — specifically Gmail and Google Docs — as standardized MCP tools.

## Features

- **`send_email`**: Send an email immediately via the authenticated Gmail account.
- **`draft_email`**: Create a draft in the authenticated Gmail account without sending.
- **`append_to_google_doc`**: Append text content to the end of an existing Google Doc.

## Setup Instructions

### 1. Google Cloud Project Setup

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project or select an existing one.
3. Navigate to **APIs & Services > Library**.
4. Search for and enable the **Gmail API** and **Google Docs API**.
5. Navigate to **APIs & Services > OAuth consent screen**.
   - Configure the consent screen (External or Internal).
   - Add the following scopes:
     - `https://www.googleapis.com/auth/gmail.send`
     - `https://www.googleapis.com/auth/gmail.compose`
     - `https://www.googleapis.com/auth/documents`
   - Add your email address as a Test User if your app is in testing mode.
6. Navigate to **APIs & Services > Credentials**.
   - Click **Create Credentials > OAuth client ID**.
   - Choose **Desktop app** as the application type.
   - Click **Create**.
   - Download the JSON file and rename it to `credentials.json`. Place it in the root of this project.

### 2. Environment Setup

1. Copy `.env.example` to `.env` (optional, as defaults are used if not provided).
2. Install the project dependencies:
   ```bash
   pip install -e .
   ```

### 3. First Run (Authentication)

Before an MCP client can use the server, you must authenticate it manually to generate the `token.json` file.

Run the server directly:
```bash
gmail-docs-mcp
```
This will open a browser window asking you to log in with your Google account and grant the requested permissions. Once completed, a `token.json` file will be created. You can then stop the server (Ctrl+C).

### 4. MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) to run this server. Add the following to your MCP client's configuration file:

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "gmail-docs-mcp",
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/absolute/path/to/token.json"
      }
    }
  }
}
```
*Note: Make sure to use absolute paths for the credentials and token files.*

## Testing

Run unit tests with pytest:
```bash
pip install -e ".[dev]"
pytest
```

## Manual Smoke-Test Checklist

1. Send test email: Invoke `send_email` with your own email address to verify receipt.
2. Create draft: Invoke `draft_email` and check your Gmail Drafts folder.
3. Append to a doc: Create a test Google Doc, copy its URL or ID, and invoke `append_to_google_doc`. Check the document to verify the text was appended at the end.