# Google MCP Server

A Python FastAPI server that integrates with **Google Docs** and **Gmail**. Each action is printed to the terminal and requires explicit approval before it runs.

## Features

| Endpoint | Description |
|---|---|
| `POST /append_to_doc` | Append text to a Google Doc |
| `POST /create_email_draft` | Create a Gmail draft |
| `GET /health` | Health check |

**Local dev:** each action is logged and prompts `Approve? (y/n)` in the terminal.

**Production (Railway):** actions are logged only; requests require the `X-API-Key` header matching the `API_KEY` secret.

## 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
├── deployment-plan.md # Railway deployment guide
├── railway.toml       # Railway deploy config
├── Procfile           # Process start command
├── credentials.json   # (NOT committed — from Google Cloud)
└── token.json         # (NOT committed — auto-generated after OAuth)
```

## Prerequisites

1. **Python 3.10+**
2. A **Google Cloud project** with these APIs enabled:
   - Google Docs API
   - Gmail API
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 **Google Docs API** and **Gmail API** under **APIs & Services → Library**.
4. Go to **APIs & Services → Credentials**.
5. Create **OAuth client ID** → Application type: **Desktop app**.
6. Download the JSON file and save it as `credentials.json` in this folder.
7. Configure the **OAuth consent screen** (External or Internal) and add your Google account as a test user if the app is in testing mode.

### OAuth scopes

- `https://www.googleapis.com/auth/documents`
- `https://www.googleapis.com/auth/gmail.compose`

## Installation

```bash
cd google-mcp-server
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

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

## First-time authentication

On the first API call (or when `token.json` is missing), a browser window opens for Google sign-in. After you approve, `token.json` is saved automatically. Later runs reuse that token and refresh it when needed.

## Run the server

```bash
python server.py
```

Or:

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

Interactive 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/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_DOC_ID\", \"content\": \"\\nHello from MCP server!\"}"
```

Watch the server terminal for the approval prompt and type `y`.

### 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\": \"Hello from the MCP server.\"}"
```

Approve in the terminal with `y`. The draft appears in Gmail under **Drafts**.

## Railway deployment

See [deployment-plan.md](deployment-plan.md) for the full guide. Summary:

1. Push this folder to GitHub and connect it in Railway (set **Root Directory** to `google-mcp-server` if needed).
2. Set these **secrets** in Railway:

| Variable | Value |
|---|---|
| `GOOGLE_CREDENTIALS_JSON` | Full contents of `credentials.json` |
| `GOOGLE_TOKEN_JSON` | Full contents of `token.json` |
| `API_KEY` | Random secret for `X-API-Key` header |
| `ENV` | `production` |

3. Optional: mount a Volume at `/data` and set `GOOGLE_TOKEN_PATH=/data/token.json` so refreshed tokens persist across redeploys.
4. Generate a public domain and call endpoints with:

```bash
curl -X POST https://YOUR-RAILWAY-URL/append_to_doc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"doc_id": "YOUR_DOC_ID", "content": "\nHello from Railway!"}'
```

Base64 variants `GOOGLE_CREDENTIALS_JSON_B64` and `GOOGLE_TOKEN_JSON_B64` are also supported if JSON escaping is awkward.

## Security notes

- **Never commit** `credentials.json` or `token.json` (they are listed in `.gitignore`).
- In production, all mutating endpoints require a valid `X-API-Key` header.
- Revoke access anytime at [Google Account permissions](https://myaccount.google.com/permissions).

## Troubleshooting

| Issue | Fix |
|---|---|
| `Missing credentials.json` | Download OAuth desktop credentials from Google Cloud Console |
| `403 access_denied` on OAuth | Add your account as a test user on the OAuth consent screen |
| `403 Action rejected` | You typed something other than `y` at the approval prompt |
| Doc append fails | Confirm the Doc ID and that the signed-in account can edit the document |
| Gmail draft fails | Confirm Gmail API is enabled and the account has Gmail access |