# Google MCP Server

A Python FastAPI server that exposes Google Docs and Gmail tools with terminal-based approval before each action.

## Features

- **POST /append_to_doc** — Append text to a Google Doc
- **POST /create_email_draft** — Create a Gmail draft
- **Approval gate** — Every action prints its name and payload, then waits for `y` in the terminal before executing

## 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
├── credentials.json   # OAuth client secrets (not committed)
└── token.json         # Saved OAuth token (not committed)
```

## Prerequisites

1. A [Google Cloud project](https://console.cloud.google.com/)
2. **Google Docs API** and **Gmail API** enabled
3. OAuth 2.0 **Desktop app** credentials downloaded as `credentials.json`

### Google Cloud setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/) → APIs & Services → Library.
2. Enable **Google Docs API** and **Gmail API**.
3. Go to APIs & Services → Credentials → Create Credentials → **OAuth client ID**.
4. Application type: **Desktop app**.
5. Download the JSON file and save it as `credentials.json` in this directory.
6. Under OAuth consent screen, add your Google account as a test user (if the app is in testing mode).

## Installation

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

Place `credentials.json` in the project root before starting the server.

## First-time authentication

On the first API call that needs Google access, a browser window opens for OAuth login. After you approve, a `token.json` file is created. Subsequent runs reuse that token (refreshing it automatically when expired).

## Run the server

```bash
python server.py
```

Or with uvicorn directly:

```bash
uvicorn server:app --host 127.0.0.1 --port 8000 --reload
```

The server runs at `http://127.0.0.1:8000`. Interactive API docs: `http://127.0.0.1:8000/docs`.

> **Important:** Run the server in a terminal where you can type `y` or `n` when prompted. Approval happens in that terminal, not in the HTTP client.

## Usage examples

### Append to a Google Doc

Find the document ID in the URL:

`https://docs.google.com/document/d/DOCUMENT_ID/edit`

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

The server terminal will show:

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

Type `y` to proceed.

### 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": "Test draft",
    "body": "This is a draft created via the MCP server."
  }'
```

Approve in the server terminal when prompted. Check Gmail → Drafts for the new message.

## OAuth scopes

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

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `credentials.json` not found | Download OAuth desktop credentials from Google Cloud Console |
| `Access blocked` during login | Add your account as a test user on the OAuth consent screen |
| `403` from API | Type `y` at the approval prompt in the server terminal |
| Token errors | Delete `token.json` and re-authenticate |

## Security notes

- Never commit `credentials.json` or `token.json`.
- This server is intended for local development with manual approval.
- Do not expose it to the public internet without proper authentication.