# Google Workspace MCP Server

This is a Python-based Model Context Protocol (MCP) style server integrating **Google Docs** and **Gmail**. It is built with FastAPI and runs on a local web server, exposing endpoints to append text to Google Documents and create email drafts in Gmail.

Before any action is executed, the server prompts the user in the terminal for approval: `Approve? (y/n)`.

---

## 📁 Project Structure

```text
google-mcp-server/
├── server.py             # FastAPI server with tool endpoints & terminal approval logic
├── auth.py               # Google OAuth 2.0 authentication flow
├── docs_tool.py          # Google Docs tool (append content to document)
├── gmail_tool.py         # Gmail tool (create email draft)
├── requirements.txt      # Python package dependencies
├── README.md             # Setup and usage instructions
├── credentials.json      # (NOT committed) OAuth client credentials downloaded from Google Cloud
└── token.json            # (NOT committed) Auto-generated user token after successful login
```

---

## ⚙️ Prerequisites

To run this server, you need to acquire a Google client configuration file:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project (or select an existing one).
3. Enable the following APIs:
   - **Google Docs API**
   - **Gmail API**
4. Set up the OAuth consent screen:
   - Choose **External** user type (or Internal if using a Google Workspace organization account).
   - Add test users (include your own Gmail address).
   - Add the scopes:
     - `https://www.googleapis.com/auth/documents` (to append to documents)
     - `https://www.googleapis.com/auth/gmail.compose` (to create drafts)
5. Create Credentials:
   - Click **Create Credentials** -> **OAuth client ID**.
   - Select application type: **Desktop app**.
   - Name it, click **Create**, and click **Download JSON**.
   - Rename the downloaded file to `credentials.json` and place it in the root of this project directory.

---

## 🚀 Setup & Installation

1. **Clone/Navigate to the workspace directory**:
   ```bash
   cd "c:\Users\amoln\Airtribe Projects\gmail_gdrive_mcp_server"
   ```

2. **Create and activate a virtual environment (optional but recommended)**:
   ```bash
   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On macOS/Linux:
   source venv/bin/activate
   ```

3. **Install the dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

---

## 🔐 Authentication

The authentication module `auth.py` automatically checks for a `token.json` file. If it doesn't exist, it opens a local browser server to execute the Google login flow.

You can trigger authentication manually before running the server:
```bash
python auth.py
```
This will open your browser. Grant the necessary permissions for Google Docs and Gmail, and the script will save `token.json` in the root folder. Future runs will read `token.json` directly and skip the browser login.

---

## 🏃 Running the Server

Start the FastAPI server:
```bash
python server.py
```

The server will start listening on `http://127.0.0.1:8005`.

---

## 🧪 API Endpoints & Usage

### 1. Append to Google Doc
- **Endpoint**: `POST /append_to_doc`
- **Request Body** (JSON):
  ```json
  {
    "doc_id": "YOUR_GOOGLE_DOCUMENT_ID",
    "content": "This text will be appended to the document.\n"
  }
  ```
- **Example request (`curl`)**:
  ```bash
  curl -X POST "http://127.0.0.1:8005/append_to_doc" \
       -H "Content-Type: application/json" \
       -d "{\"doc_id\": \"1234567890abcdefghijklmnopqrstuvwxyz\", \"content\": \"Hello Google Docs!\n\"}"
  ```

### 2. Create Gmail Draft
- **Endpoint**: `POST /create_email_draft`
- **Request Body** (JSON):
  ```json
  {
    "to": "recipient@example.com",
    "subject": "Hello from MCP Server",
    "body": "This is the body of the draft email."
  }
  ```
- **Example request (`curl`)**:
  ```bash
  curl -X POST "http://127.0.0.1:8005/create_email_draft" \
       -H "Content-Type: application/json" \
       -d "{\"to\": \"recipient@example.com\", \"subject\": \"Test Subject\", \"body\": \"This is a test draft body.\"}"
  ```

---

## 🛡️ Terminal Approval Prompt

Whenever a request is sent to either of the endpoints, the server output will print the request details in the terminal and block:

```text
========================================
ACTION NAME: append_to_doc
PAYLOAD:
  doc_id: 1234567890abcdefghijklmnopqrstuvwxyz
  content: Hello Google Docs!
========================================
Approve? (y/n): 
```

- **Type `y` and press Enter**: The action is sent to the Google APIs. The client receives a `200 OK` response.
- **Type `n` and press Enter**: The action is rejected. The API blocks execution and returns a `403 Forbidden` response: `{"detail":"Action rejected by user."}`.