Google Sheets API integration (Nango)

A working Google Sheets API integration you can clone and run: customer OAuth, a row sync, write-back actions, and an AI agent that calls them. It is the companion repo for How to build a Google Sheets API integration with Nango.

The Nango functions here (one sync, four actions) were written by a coding agent (Codex, Claude Code, or Cursor) using the Nango function builder skill. Nango runs them with managed Google OAuth, retries, and logging.

"YourApp" is the sample product. A customer connects their own spreadsheet, the rows show up in a table, and they (or an AI agent) can write back.

What it does

• Connect a sheet. Customers authorize Google with Nango Connect and pick a spreadsheet. No OAuth code in your app.
• Sync rows. A sync imports the rows and refreshes hourly, since the Sheets API has no webhooks.
• Write back. Append a row, edit a row inline, or find and replace across the sheet.
• Agent access. An in-app assistant runs those actions through Nango's MCP server, scoped to the user's connection.

Project structure

frontend/            Static UI (no build step)
backend/             Express server: serves the UI, exposes /api, holds the Nango secret key
nango-integrations/  The Nango functions (the integration itself)
  google-sheet/
    syncs/fetch-spreadsheet-rows.ts   import rows, refresh hourly
    actions/append-row.ts             add a row
    actions/update-row.ts             overwrite a row by number
    actions/find-replace.ts           bulk find and replace
    actions/list-rows.ts              read rows (used by the agent)

The browser only talks to the backend at http://localhost:3000. Secrets stay on the server.

Prerequisites

• Node 22 or newer.
• A free Nango account.
• The Google Sheets integration set up in Nango with the unique key google-sheet (the code uses this key). Use Nango's shared dev credentials, or register your own Google OAuth app.
• A connection for a Google account that owns a spreadsheet with a few rows. An empty or unshared sheet syncs nothing.
• Optional: an Anthropic API key for the in-app agent. The rest runs without it.

Run it

Deploy the functions first. The sync, actions, and agent all call deployed functions, so this is a required build step.

1. Deploy the Nango functions:

   cd nango-integrations
   npm install
   cp .env.example .env      # set NANGO_SECRET_KEY_DEV
   npx nango deploy dev

2. Start the backend (it also serves the UI):

   cd ../backend
   npm install
   cp .env.example .env      # NANGO_SECRET_KEY, plus an optional ANTHROPIC_API_KEY
   npm start

3. Open http://localhost:3000, connect a Google account, paste a spreadsheet URL, and the rows sync in.

With no Nango key set, the app runs a self-contained demo with in-memory rows, so you can click through the UI without an account.

How it works

• Sync (fetch-spreadsheet-rows): reads the sheet with values.get, maps rows to a typed model, and batchSaves them into Nango's cache. The backend serves them with nango.listRecords, and a Refresh button triggers a run on demand with triggerSync.
• Actions: append-row (values.append, valueInputOption=USER_ENTERED, insertDataOption=INSERT_ROWS, retries: 0), update-row (values.update), find-replace (batchUpdate findReplace), and list-rows (values.get).
• Agent (backend/agent.js): a Claude tool-use loop that runs the actions through Nango's hosted MCP server. It passes the connection id and google-sheet as headers, so each user's agent acts on their own sheet. The Nango and Anthropic keys stay on the backend.

Common issues

• Integration key mismatch. The provider config key is google-sheet. Keep it, or set NANGO_INTEGRATION_ID in backend/.env.
• Nothing syncs. The connected sheet is empty, or not shared with the authorized account.
• Functions not found. Deploy them first (step 1). listRecords, triggerSync, and triggerAction need deployed functions.
• Assistant gives scripted replies. ANTHROPIC_API_KEY is not set. The sync and actions still work.

Tests

cd nango-integrations && npm install && npm test

The specs run against recorded API responses in google-sheet/tests/.

---

Full walkthrough: How to build a Google Sheets API integration with Nango.