apps-script-mcp-server

An MCP server that lets Claude read and push Google Apps Script (.gs, .html, appsscript.json) code directly into a script project — no more copy-pasting code into the Apps Script editor by hand.

Built for the Kwara disease surveillance system (KWARAB dashboard), but works with any Apps Script project you have edit access to.

What it can do

Important limitation to know up front: pushing code with apps_script_update_file / apps_script_update_content updates the editable project, the same as typing in the script editor and saving. It does not automatically update anything already deployed (e.g. a live web app URL, or triggers bound to a specific deployed version). To go live with changes, create a version (apps_script_create_version) and then redeploy from the Apps Script editor — this server doesn't touch deployment publishing, on purpose, since that's a more consequential action worth doing by hand the first few times.

1. One-time Google Cloud setup (do this first)

You need a Google Cloud project with the Apps Script API enabled and an OAuth client. This takes about 5 minutes.

1. Create or pick a Google Cloud project Go to https://console.cloud.google.com/projectcreate and create a project (any name is fine — e.g. "kwarab-apps-script-mcp"). If you already have a GCP project you use for other Kwara/Ekiti work, you can reuse it.

2. Enable the Apps Script API on the project Go to https://console.cloud.google.com/apis/library/script.googleapis.com, select your project, and click Enable.

3. Configure the OAuth consent screen Go to https://console.cloud.google.com/apis/credentials/consent

   • User type: External (unless you have a Google Workspace org, then Internal is fine)

   • Fill in app name (e.g. "Apps Script MCP"), your email as support contact

   • Scopes: you can skip adding scopes here — the server requests them directly

   • Test users: add your own Google account email (required while the app is in "Testing" status, which is fine for personal/internal use)

4. Create an OAuth client Go to https://console.cloud.google.com/apis/credentials

   • Click Create Credentials → OAuth client ID

   • Application type: Desktop app

   • Name it anything (e.g. "Apps Script MCP Desktop")

   • Click Create, then Download JSON

5. Save the downloaded file as credentials.json in this project's root folder (same folder as this README). Do not commit or share this file — it identifies your OAuth client (not your personal account, but still keep it private).

6. Enable the Apps Script API for your own Google account This is separate from step 2 (that enables the API for the project; this enables it for the Google account that owns/edits the script). Go to https://script.google.com/home/usersettings and turn on "Google Apps Script API".

2. Install and authorize

npm install
npm run build
npm run authorize

npm run authorize opens your browser, asks you to sign in with the Google account that has access to the Kwara disease surveillance Apps Script project, and asks you to approve access. After approving, it saves a refresh token to token.json in this folder — you only need to do this once (re-run it if you ever revoke access or switch Google accounts).

If nothing opens automatically: the terminal will print a URL — copy-paste it into any browser, approve, and you'll be redirected back to localhost where the script is listening; the terminal will confirm success.

3. Connect it to Claude

Option A: Local (stdio) — Claude Code / Claude Desktop

Add to your MCP config (e.g. claude_desktop_config.json or your Claude Code MCP settings):

{
  "mcpServers": {
    "apps-script": {
      "command": "node",
      "args": ["/absolute/path/to/apps-script-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop / Claude Code after adding this. You should see apps-script listed among connected MCP servers, with tools like apps_script_update_file available.

Option B: Remote (HTTP), e.g. hosted on Render

The server also runs as a standalone HTTP service — set TRANSPORT=http. This is what render.yaml in this repo configures automatically. See Deploying to Render below.

A remote server is reachable by anyone who has its URL, so every request to /mcp must include a bearer token matching the MCP_SERVER_TOKEN environment variable you set:

Authorization: Bearer <your MCP_SERVER_TOKEN value>

In Claude's remote MCP connector settings, add the server URL (https://<your-service>.onrender.com/mcp) and set that header. /healthz is intentionally unauthenticated so Render's health checks can reach it.

Deploying to Render

This repo includes a render.yaml Blueprint, so Render can create the service with most settings pre-filled.

1. In the Render dashboard: New → Blueprint, connect your GitHub account if you haven't already, and select this repository. Render will read render.yaml.

2. Render will prompt you for the environment variables marked sync: false:

   • MCP_SERVER_TOKEN — make up a long random string (e.g. openssl rand -hex 32). This is what Claude must send as the bearer token.

   • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REFRESH_TOKEN — generate these locally first (steps 1–2 above, including npm run authorize), then open the resulting token.json and copy client_id, client_secret, and refresh_token into Render's environment variable fields. Render never gets a browser, so this headless-credential path replaces the local npm run authorize step.

3. Deploy. Once live, the MCP endpoint is https://<your-service>.onrender.com/mcp.

4. On the free plan, Render spins the service down after inactivity — the first request after idling will be slow (cold start) while it spins back up.

4. Using it

You'll need the script ID of the Kwara disease surveillance Apps Script project. Find it by opening the project at https://script.google.com, and copying the ID out of the URL:

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

(If the Apps Script is bound to the KWARAB Google Sheet rather than standalone, open the sheet → Extensions → Apps Script to get to the same editor and URL.)

Then, in a Claude conversation with this MCP server connected, you can say things like:

• "Show me the current Code.gs in script <scriptId>"

• "Update the sendAlertEmail function in Code.gs to also CC the DSNO supervisor"

• "Push this new Utils.gs file with these helper functions: ..."

• "Create a new version called 'Add AFP EPID auto-compose logic'"

Security notes

• credentials.json and token.json both grant access to Apps Script projects you can edit. Keep them out of version control (a .gitignore is included) and don't share them.

• The OAuth scopes requested (script.projects, script.deployments) do not include Gmail, Sheets, or Drive access beyond what's needed to read/write script project content and inspect deployments.

• To revoke access at any time: https://myaccount.google.com/permissions → find the OAuth client name you set in step 4 above → Remove Access. Delete token.json afterward.

Troubleshooting