How to use Google Sheets as a database for AI agents

An AI agent needs somewhere to keep the data it works on: the leads it qualifies, the tickets it triages, the content calendar it fills, the inventory it checks, the log of what it did. For a lot of these projects the right place is a spreadsheet, not a database server, because the people who supervise the agent already live in spreadsheets. They can see every row the agent touched, fix a value by typing over it, and add rows of their own without an admin panel.

This page is about that setup: a Google Sheet as the database behind an agent. It covers when a spreadsheet is a good fit and when it is not, how the pieces connect (agent → MCP → SheetDB → sheet), how to structure the sheet, and the part that decides whether you can sleep at night: what the agent may do with your data, and what it may never do. SheetDB is the layer in the middle; the setup per assistant is on the MCP server page.

When a spreadsheet is a good database for an agent

A spreadsheet is a table with a human-friendly editor attached. That is exactly what an agent project needs when:

• People need to see what the agent does. A sales team reviewing qualified leads, an editor checking generated summaries, an operations person correcting an inventory count. Every write lands in a sheet they already have open, with Google's version history behind it.
• The data is small. Up to a few tens of thousands of rows per tab, hundreds of thousands at most across tabs. An agent rarely needs more; it needs the right rows, found by a filter.
• Writes are occasional. An agent that appends a few rows per conversation, or updates the rows it was asked about, is well within Google's quotas. A pipeline that writes thousands of rows an hour is not.
• The agent is one of several clients. The same sheet feeds a table on your website, an n8n or Make workflow, a form and a script. One API serves all of them with one set of permissions.
• Setup time matters more than throughput. You can go from an idea to an agent reading real data in a few minutes, and move to a database later by exporting the sheet.

When it is the wrong tool

Be honest with yourself before the agent is. A spreadsheet is a bad database for an agent when:

• The data is sensitive. An agent reads whole rows. If a tab mixes customer e-mails with payment details, the agent sees the payment details too. Keep secrets, credentials and personal data in a spreadsheet, or a tab, that no API serves.
• Writes compete. Two agents, or an agent and a workflow, updating the same rows at the same time will race. A sheet has no transactions and no row locks.
• A change spans rows. "Move 50 from this account to that one" needs an atomic update across two rows. Google Sheets cannot promise that, and neither can any API on top of it.
• The agent is the only reader. If no human ever opens the sheet, you are paying the price of a spreadsheet (size limits, quotas, text-only cells) without its benefit. Use a database.
• The table will grow into millions of rows. Every read fetches the whole tab from Google before filtering, so response time grows with row count. The general limits are on the Google Sheets as a database page.

The architecture: agent → MCP → SheetDB → Google Sheets

Four pieces, each with one job. The agent decides what to do; MCP is how it asks; SheetDB checks whether it may and talks to Google; the spreadsheet holds the data and shows it to people.

The step that is easy to skip, and should not be, is the third one. Without it the agent talks to Google directly, with a token that has the full Sheets scope of whoever signed in. That is raw access: whatever the person can do, the agent can do, in one call, with nobody in between. Google's own Sheets MCP server, in developer preview at the time of writing, works that way by design: your Cloud project, your consent screen, an OAuth client marked for an AI agent, and tools that read and update cells, formulas and structure with the user's full permissions. It is the right tool for an agent that must format a workbook. It is a lot of trust for an agent that should only append leads to one tab.

SheetDB narrows that trust. The agent never holds a Google token; it holds an Agent connection to SheetDB that you approve once and can revoke with one click. It sees only the APIs you created, each bound to one spreadsheet, and only the operations you enabled for that API. Reads go through the same cache as the REST API (15 seconds by default, configurable per API), so an agent asking the same question twice costs Google nothing. Writes clear the cache, so the next read is fresh.

What the agent can do with the sheet

The MCP server exposes ten tools, and an agent uses them the way you would use a small data API: discover, read, filter, then write. A typical first exchange on the public demo spreadsheet (https://docs.google.com/spreadsheets/d/1YiMOrIFnMaksK032-zv6Sch2tTVTRhEpsFom_5qSLXM/edit) looks like this:

1. list_apis returns the APIs of your account with their api_id and what the agent may do on each.
2. describe_api returns the tabs, the column names, the record count and three sample records, so the agent learns the shape of the data before it asks for anything.
3. search_records finds rows by value, with the same operators as /search over HTTP:

{"api_id": "58f61be4dda40", "conditions": {"comment": "special"}}

{
  "total": 1,
  "offset": 0,
  "limit": 100,
  "has_more": false,
  "next_offset": null,
  "records": [{ "id": "4", "name": "Steve", "age": "22", "comment": "special" }]
}

From there the agent appends rows with create_records (special values such as INCREMENT and TIMESTAMP work as over HTTP), changes matching rows with update_records, and proposes deletes with delete_records, which never deletes by itself (next section). create_api_from_spreadsheet lets it turn a spreadsheet URL into a new API when you ask for one. The tool parameters are in the MCP server documentation.

Not exposed through MCP, on purpose: deleting a whole tab, creating or deleting tabs, editing single cells, JSON import, cache purge and statistics. Those stay in the panel and the REST API, where a person or a script runs them deliberately.

How to structure the sheet for an agent

The advice for any sheet used as a database applies: column names in the first row, one tab per table, an id column, consistent types, no merged cells. Agents add a few rules of their own:

• Name columns the way you would say them. The agent matches your question ("which leads are unqualified?") to column names. status and owner work better than col_7 or S. Short, lowercase, no spaces.
• Give the agent a status column. A queue-like workflow (new → in progress → done) lets the agent pick its work with one search (status = new) and mark it with one update, instead of reading the whole tab to decide what is left.
• Add a tab the agent appends to. A log or activity tab that the agent only ever adds rows to (what it did, when, for which id) gives you an audit trail inside the sheet. Give agents the create permission on that tab's API and nothing else.
• Keep instructions out of cells. The agent reads cell values as data, and SheetDB's tool descriptions say so, but a column of "notes for the AI" invites exactly the kind of text you do not want a model to read as a command. Put the agent's instructions in your prompt or the client, not in the spreadsheet.
• Split by sensitivity, not by topic. One API per spreadsheet, so one spreadsheet per level of trust: a sheet the agent may write to, a sheet it may only read, and sheets it never sees. Agent permissions are set per API.
• Keep tabs small. Reads are paginated and fetch the tab from Google before filtering. Archive finished rows to another spreadsheet now and then; the agent will be faster and cheaper.

Security: what the agent may do, and what it may never do

An agent that writes to your data is useful exactly to the degree you trust what it will not do. SheetDB does not rely on the model being careful, nor on the client's confirmation dialog, which every MCP client lets the user switch off. The protection lives on the server, in three layers.

Agent permissions per API

When your first agent connects, every API in your account gets an AI agents section in its settings. Agents may only read until you switch on create, update or delete for that API. These Agent permissions are an intersection with the API's own permissions: if DELETE is off for the API over HTTP, no agent setting turns it on. A refused tool returns one plain sentence with a link to the right settings page, so the agent tells you where to enable the operation instead of retrying.

Approval before a delete or a mass update

delete_records only works with a condition and deletes nothing. It counts the matching rows, stores a Pending action and returns a preview written by SheetDB, not by the model: how many rows, a sample of up to 10, and an id. What happens next depends on the size of the change and on the Approval threshold of the API:

• Up to 10 rows and 5% of the tab (the default): the agent shows you the preview and, after you agree in the chat, calls confirm_pending_action with the exact count it expects. The server refuses if the count differs, re-reads the rows from Google right before deleting and stops if they changed in the meantime.
• Above the threshold, or on an API set to always approve in panel: the agent gets a link to the SheetDB panel. You see the rows, with the changed cells highlighted for an update, and click Approve or Reject while signed in. That approval never passes through the AI client, so no model and no client setting can fake it.
• A Pending action is one-time, bound to the agent that proposed it, and expires after 5 minutes in the chat and 15 in the panel. Rejected and expired actions report a clear status, so the agent does not retry in a loop.

The chat path is a damage limit, not a human approval: the change is small, the server checks the count and re-reads the rows, and Google's version history is there if something still goes wrong. The panel is the real approval, and the only one that does not depend on which client the agent runs in. Owners who want no questions at all can set the threshold to no approval per API; the default is deliberately cautious.

Limits that always apply

• The agent sees only the APIs you see in the panel: your own and, with Shared APIs in a team, your team's. Never anyone else's, and never internal identifiers.
• Every call checks, in order: your sign-in and the Agent connection, your access to the API, the API permissions, the Agent permissions and the threshold.
• Per-API rate limits and the cache apply as for HTTP, plus a limit of 30 tool calls per minute per Agent connection. An agent stuck in a loop is told to slow down instead of exhausting your quota.
• Cell values are data, never instructions. The server instructions and tool descriptions tell the model so, and the instructions a tool result contains (such as the next step after a preview) come only from SheetDB's own templates.
• Revoke any Agent connection with one click under AI agents in the panel; the agent is signed out at once.

Agents without MCP: the REST API and OpenAPI

Not every agent runs in a chat client. If you write the agent yourself, in an agent framework or in plain code, give it the REST API instead: the same read, search, create, update and delete operations, one URL per sheet, JSON in and out. The whole API is described in an OpenAPI 3.1 document at sheetdb.io/openapi.json (also as YAML), which frameworks that take OpenAPI, client generators and tools such as Postman import directly.

const api = 'https://sheetdb.io/api/v1/58f61be4dda40';

// The agent's tool: find rows by column value.
const params = new URLSearchParams({ comment: 'special' });
const rows = await fetch(`${api}/search?${params}`).then((response) => response.json());

// The agent's tool: append a row it was asked to add.
await fetch(api, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: [{ id: 'INCREMENT', name: 'Mark', age: '35', comment: 'new lead' }] }),
});

Two differences from MCP to plan for. First, the REST API authenticates with a Bearer token or HTTP Basic auth per API, which your code holds, so keep it in your environment, not in a prompt. Second, the Pending action is an MCP feature: over HTTP a DELETE runs on the call, as it does for any script. If your framework agent may delete, keep the delete permission off for that API and route deletions through a human, or through the MCP server. Guides for the languages and tools: PHP, Node.js, n8n and Make.

Limits and cost

Two sets of limits apply, as for any sheet used as a database. Google's: at most 10 million cells per spreadsheet, 50,000 characters per cell, and a per-minute quota on reads and writes that you cannot raise. SheetDB's: each plan includes a monthly number of requests, bursts are rate limited per API, and reads return at most a few thousand rows per call, paginated. The current numbers are on the limits page.

A tool call that reads or writes records counts as one request, like one HTTP request, regardless of how many rows it returns. Listing APIs, checking or confirming a Pending action and creating an API are free. The statistics of each API show how many requests came from AI agents, so you can see what an assistant costs you before you decide on a plan. MCP is included in every plan, including the free plan.

Get started

1. Sign in to SheetDB with Google, click Create new API and paste the spreadsheet URL. You get an api_id and an endpoint.
2. Add https://sheetdb.io/mcp to your assistant and sign in: Claude, ChatGPT and Cursor have step-by-step guides, and the MCP page covers Claude Code and other clients.
3. Ask the agent what is in the sheet. Then open the API settings, decide which operations it may do under AI agents, and leave the approval threshold where it is until you have seen a few previews.

FAQ

[
  {
    "id": "1",
    "name": "Tom"
  }, …
]