Poke ↔ Google Docs MCP

A remote MCP server that lets your Poke agent create and edit Google Docs. Built with Python + FastMCP, deployable to Render in a few minutes, and structured so you can extend it to Sheets, Drive, and other Google APIs.

Auth model: single-tenant per deployment. You (or anyone who forks this) bring your own Google OAuth client and mint your own refresh token. There's no shared multi-user server to run — clone it, plug in your credentials, deploy.

Tools

A document ID is the long string in a Doc's URL: https://docs.google.com/document/d/THIS_PART/edit.

Related MCP server: LLM2Docs (Unofficial)

Setup

1. Google Cloud: create OAuth credentials

1. Go to the Google Cloud Console and create (or pick) a project.

2. APIs & Services → Library → enable the Google Docs API. (Enable Google Sheets API / Google Drive API here too if you extend later.)

3. APIs & Services → OAuth consent screen:

   • User type: External.

   • Fill in app name + your email.

   • Under Test users, add your own Google address. (In "Testing" mode the refresh token works indefinitely for test users.)

4. APIs & Services → Credentials → Create Credentials → OAuth client ID:

   • Application type: Desktop app.

   • Download the JSON, rename it to client_secret.json, and put it in this project's root folder.

2. Mint your refresh token (one time, local)

pip install -r requirements.txt
python setup_auth.py

A browser opens — sign in and approve. The script prints:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...

Keep these secret.

3. Generate an API key for Poke

This protects your public server URL so only Poke can use it:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Save the output as MCP_API_KEY.

4. Deploy to Render

Fork this repo first (so the env vars are yours), then click the button on your fork's README — or do it manually:

1. Push this repo to your own GitHub.

2. In Render: New → Blueprint (it auto-detects render.yaml) or New → Web Service, and connect your repo.

3. Add these environment variables (Environment tab):

   • GOOGLE_CLIENT_ID

   • GOOGLE_CLIENT_SECRET

   • GOOGLE_REFRESH_TOKEN

   • MCP_API_KEY

4. Deploy. Your server is at https://<your-service>.onrender.com/mcp.

Render's free tier sleeps when idle, so the first request after a pause has a cold-start delay of ~30s. Upgrade the plan if that bothers you.

5. Connect it to Poke

In Poke → Settings → Integrations → Connect MCP (or poke.com/settings/connections):

• URL: https://<your-service>.onrender.com/mcp

• API Key: the MCP_API_KEY from step 3.

Then ask Poke something like: "Create a Google Doc called 'Weekly Plan' and add a heading and three bullet points."

Run locally

cp .env.example .env        # fill in the values from setup_auth.py
# load .env into your shell, then:
python src/server.py        # serves http://localhost:8000/mcp

To expose a local server to Poke for testing, tunnel it with e.g. ngrok http 8000 and give Poke the https://…/mcp URL.

Extending to Sheets, Drive, etc.

The codebase is built for this:

1. Add the scope in src/config.py (e.g. uncomment the Sheets scope) and re-run python setup_auth.py to get a token with the new permission.

2. Enable the API in Google Cloud (e.g. Google Sheets API).

3. Add a client helper in src/google_client.py:

   def sheets_service():
       return get_service("sheets", "v4")

4. Copy src/tools/docs.py → src/tools/sheets.py, write a register_sheets_tools(mcp) with your new @mcp.tool() functions.

5. Register it in src/server.py:

   from tools.sheets import register_sheets_tools
   register_sheets_tools(mcp)

Every tool just needs the @require_auth decorator (under @mcp.tool()) to stay protected by your API key.

How it works / security notes

• Transport: streamable HTTP at /mcp, stateless — the format Poke expects.

• MCP auth: every tool checks Authorization: Bearer <MCP_API_KEY> via the @require_auth decorator. If MCP_API_KEY is unset, auth is disabled — only do that locally.

• Google auth: a long-lived refresh token (yours) is exchanged for short-lived access tokens automatically by google-auth.

• Secrets live in env vars only. .gitignore excludes .env, client_secret.json, and token.json so they never reach git.

Project layout

setup_auth.py          # one-time: mint your refresh token
render.yaml            # Render deploy config
requirements.txt
.env.example
src/
  server.py            # FastMCP app + HTTP transport; registers tool modules
  config.py            # OAuth scopes (single source of truth)
  auth.py              # Bearer-token check for the MCP server (@require_auth)
  google_client.py     # builds cached, auto-refreshing Google API clients
  tools/
    docs.py            # Google Docs tools  (template for new services)