# Personal Google MCP Server

Gives Claude read/write access to **your own** Gmail, Google Docs, Google Sheets,
and Google Tasks. Runs as a tiny always-on web service so it works from Claude
on your phone with your computer off.

Tools included: `sheets_read`, `sheets_write`, `sheets_append`, `docs_read`,
`docs_append_text`, `gmail_search`, `gmail_read`, `gmail_create_draft`,
`gmail_send`, `tasks_list`, `tasks_create`, `tasks_update`.

Cost: **$0/month** (Render free tier + Google APIs are free for personal use).

---

## Step 1 — Create a Google Cloud project + OAuth credentials (~10 min)

1. Go to https://console.cloud.google.com/projectcreate — create a project (any name).
2. Go to **APIs & Services → Library** and enable, one by one:
   - Google Sheets API
   - Google Docs API
   - Gmail API
   - Tasks API
3. Go to **APIs & Services → OAuth consent screen**.
   - User type: **External**. App name: anything. Add your own email as a **test user**.
   - You do NOT need to submit for verification — test mode works indefinitely for you as a test user.
4. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
   - Application type: **Desktop app**.
   - Save the **Client ID** and **Client Secret** shown.

## Step 2 — Get a refresh token (run once, on your own computer)

You need [Node.js](https://nodejs.org) installed locally for this one step only.

```bash
# unzip the project folder first, then:
cd google-mcp-server
npm install
node get-token.js YOUR_CLIENT_ID YOUR_CLIENT_SECRET
```

Open the URL it prints, approve access with your Google account, and it will
print a `GOOGLE_REFRESH_TOKEN=...` value in your terminal. Save that — you
won't do this step again unless you revoke access.

## Step 3 — Deploy to Render (free, no credit card)

1. Push this folder to a new **private** GitHub repo.
2. Go to https://render.com → sign up free → **New → Web Service** → connect that repo.
3. Settings:
   - Build command: `npm install`
   - Start command: `npm start`
   - Instance type: **Free**
4. Add environment variables (Render dashboard → Environment):
   - `GOOGLE_CLIENT_ID` — from Step 1
   - `GOOGLE_CLIENT_SECRET` — from Step 1
   - `GOOGLE_REFRESH_TOKEN` — from Step 2
   - `MCP_SECRET_PATH` — make up a long random string (e.g. run
     `node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"`
     and use the output). This acts as your connector's password — anyone
     with this exact URL can access your Google account through it, so keep
     it private and don't commit it to a public repo.
5. Deploy. Render gives you a URL like `https://your-app.onrender.com`.

Note: Render's free tier spins the service down after 15 minutes of no
traffic, so the first request after a break takes ~30–50 seconds to wake up.
That's normal — just wait for it once.

## Step 4 — Add it to Claude

1. In the Claude app: **Settings → Connectors → Add custom connector**.
2. Name: anything (e.g. "My Google Tools").
3. URL: `https://your-app.onrender.com/mcp/YOUR_MCP_SECRET_PATH`
4. Leave OAuth fields blank — save.
5. In a chat, enable the connector (`+` → Connectors) and try: *"list my Google Tasks"* or *"read Sheet [ID], tab Trip"*.

This works identically on your phone and desktop, since the server lives on
Render, not on your computer.

## Notes / limits

- This is single-user: it only ever acts as **you** (whoever ran Step 2).
  Don't share the URL.
- `gmail_send` sends immediately — no confirmation step. If you'd rather
  always review before sending, just tell Claude to use `gmail_create_draft`
  instead, or remove the `gmail_send` tool from `index.js`.
- To add more tools later (Calendar, Drive search, etc.), copy the pattern of
  any existing `server.registerTool(...)` block in `index.js`.