# Google Docs/Sheets MCP Server

A remote MCP server that lets Claude actually edit your existing Google Docs
and Sheets — not just read them or create new ones.

Tools it exposes:

- `docs_search`, `docs_read`, `docs_replace_text`, `docs_append_text`, `docs_insert_text_at`, `docs_create`
- `sheets_search`, `sheets_read`, `sheets_update_cells`, `sheets_append_rows`, `sheets_create`

This server acts as **your** Google account only (whichever account you
authorize in Step 2). It's meant for personal or single-team use, not as a
multi-tenant public service.

---

## Step 1 — Create a Google Cloud OAuth client

1. Go to https://console.cloud.google.com/ and create a project (or use an existing one).
2. Go to **APIs & Services → Library** and enable:
   - Google Docs API
   - Google Sheets API
   - Google Drive API
3. Go to **APIs & Services → OAuth consent screen**. Choose **External**, fill in
   the required fields, and add yourself as a test user. (You don't need to
   publish the app — test mode works fine for personal use.)
4. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
   - Application type: **Desktop app**
   - Save the generated **Client ID** and **Client Secret**.

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

```bash
cd gdocs-mcp-server
npm install

GOOGLE_CLIENT_ID=your_client_id \
GOOGLE_CLIENT_SECRET=your_client_secret \
npm run get-token
```

This opens a URL for you to visit — log in and approve access. The script
prints a `GOOGLE_REFRESH_TOKEN` value in your terminal. Save it; you'll need
it in Step 3.

## Step 3 — Deploy the server

Pick any host that runs a persistent Node.js process and gives you a public
HTTPS URL. **Render.com** is a straightforward free option:

1. Push this folder to a GitHub repo (or use Render's "public Git repo" deploy).
2. On Render: **New → Web Service**, connect the repo.
3. Build command: `npm install`
4. Start command: `npm start`
5. Add environment variables (from **Environment** tab):
   - `GOOGLE_CLIENT_ID`
   - `GOOGLE_CLIENT_SECRET`
   - `GOOGLE_REFRESH_TOKEN` (from Step 2)
   - `MCP_ACCESS_TOKEN` — make up a long random secret (e.g. run `openssl rand -hex 32` locally)
6. Deploy. Render will give you a URL like `https://your-app.onrender.com`.

Your MCP endpoint is then: `https://your-app.onrender.com/mcp`

(Railway, Fly.io, or a small VPS all work the same way — the only requirement
is a public HTTPS URL and the same environment variables.)

## Step 4 — Connect it to Claude

1. In Claude, go to **Settings → Connectors**.
2. Click **"+"** → **Add custom connector**.
3. Paste in your server URL: `https://your-app.onrender.com/mcp`
4. Click **Advanced settings** → under **Request headers**, add:
   - Header name: `Authorization`
   - Header value: `Bearer YOUR_MCP_ACCESS_TOKEN` (the same secret from Step 3)
5. Click **Add**, then **Connect**.
6. In any chat, use the **"+"** button → **Connectors** → toggle this one on.

You can now ask Claude things like "update cell B2 in my Q3 budget sheet to
5000" or "replace 'draft' with 'final' throughout my proposal doc" and it
will actually make the change.

---

## Testing locally before you deploy

```bash
cp .env.example .env
# fill in .env with your values
npm install
npm start
```

The server listens on `http://localhost:3000/mcp`. You won't be able to point
Claude's hosted product at `localhost` directly (it needs a public URL), but
this is useful for catching errors before you deploy.

## Notes and limitations

- This server edits Docs/Sheets as **whichever Google account you authorized**
  in Step 2 — anyone using this connector acts as that account.
- `docs_replace_text` replaces plain text only; it won't preserve rich
  formatting differences between the old and new text.
- Sheets values are written with `USER_ENTERED` input, so formulas like
  `=SUM(A1:A10)` are interpreted, not stored as literal text.
- If you ever want to revoke access, go to
  https://myaccount.google.com/permissions and remove the app.