# Google MCP Server

A Python FastAPI server that exposes Google Docs and Gmail operations with interactive terminal approval before each action.

## Features

- **POST /append_to_doc** — Append text to an existing Google Doc
- **POST /create_email_draft** — Create a Gmail draft email
- **Interactive approval** — Every action prints its name and payload to the terminal and waits for `y` before proceeding
- **OAuth 2.0** — Authenticates once via browser; reuses `token.json` on subsequent runs

## Project Structure

```
google-mcp-server/
├── server.py          # FastAPI app with tool endpoints
├── auth.py            # Google OAuth authentication
├── docs_tool.py       # Google Docs tool (append content)
├── gmail_tool.py      # Gmail tool (create draft)
├── requirements.txt   # Dependencies
├── README.md          # This file
├── credentials.json   # (NOT committed) OAuth client secrets from Google Cloud
└── token.json         # (NOT committed) Auto-generated after first login
```

## Prerequisites

1. Python 3.10+
2. A Google Cloud project with **Google Docs API** and **Gmail API** enabled
3. OAuth 2.0 Desktop client credentials downloaded as `credentials.json`

## Google Cloud Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/).
2. Create or select a project.
3. Enable these APIs:
   - [Google Docs API](https://console.cloud.google.com/apis/library/docs.googleapis.com)
   - [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
4. Configure the OAuth consent screen (External or Internal, add your email as a test user if External).
5. Create credentials:
   - **APIs & Services → Credentials → Create Credentials → OAuth client ID**
   - Application type: **Desktop app**
   - Download the JSON file and save it as `credentials.json` in this directory.

## Installation

```bash
cd google-mcp-server
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

Place your downloaded `credentials.json` in the `google-mcp-server/` directory.

## First-Time Authentication

On the first API call (or when `token.json` is missing/expired), a browser window opens for Google sign-in. After approval, credentials are saved to `token.json` and reused automatically.

To authenticate ahead of time:

```bash
python -c "from auth import get_credentials; get_credentials()"
```

## Run the Server

```bash
python server.py
```

The server listens at `http://127.0.0.1:8000`. Keep the terminal visible — approval prompts appear there.

Interactive API docs: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)

## Usage Examples

### Append to a Google Doc

Find the document ID in the URL: `https://docs.google.com/document/d/<DOC_ID>/edit`

```bash
curl -X POST http://127.0.0.1:8000/append_to_doc \
  -H "Content-Type: application/json" \
  -d '{"doc_id": "YOUR_DOC_ID", "content": "\nHello from the MCP server!\n"}'
```

The terminal shows:

```
============================================================
Action: append_to_doc
Payload: {'doc_id': '...', 'content': '...'}
============================================================
Approve? (y/n):
```

Type `y` to proceed, or anything else to reject (returns HTTP 403).

### Create a Gmail Draft

```bash
curl -X POST http://127.0.0.1:8000/create_email_draft \
  -H "Content-Type: application/json" \
  -d '{"to": "recipient@example.com", "subject": "Hello", "body": "Draft created via API."}'
```

Approve in the terminal when prompted. The draft appears in Gmail under **Drafts**.

## OAuth Scopes

| Scope | Purpose |
|-------|---------|
| `https://www.googleapis.com/auth/documents` | Read and modify Google Docs |
| `https://www.googleapis.com/auth/gmail.compose` | Create and manage Gmail drafts |

## Security Notes

- Never commit `credentials.json` or `token.json` (both are in `.gitignore`).
- The approval gate is a local safety check — run the server only on trusted machines.
- Revoke access anytime at [Google Account Permissions](https://myaccount.google.com/permissions).

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `FileNotFoundError: Missing credentials.json` | Download OAuth desktop credentials from Google Cloud Console |
| `403 access_denied` during OAuth | Add your Google account as a test user on the OAuth consent screen |
| `403 Action rejected by user` | You declined the prompt; retry and type `y` |
| Token expired | Delete `token.json` and re-authenticate, or let the server refresh automatically |