# How to connect Google Sheets to Hermes Agent (no API keys)

> Connect Google Sheets to Hermes Agent with no Google Cloud project, no OAuth client, and no credentials JSON. Hosted OAuth, 40 Sheets tools, and fixes for the Sheets API errors agents actually hit.

Web version: https://claw-link.dev/hermes/google-sheets

Most guides for giving Hermes Agent Google Sheets access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Google Sheets setup: pair once in the browser and your always-on Hermes agent can act on Google Sheets for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Google Sheets.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Google Sheets** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect google-sheets  # connect Google Sheets (browser OAuth)
npx -y @useclawlink/cli actions google-sheets  # list available actions
npx -y @useclawlink/cli run google-sheets <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Google Sheets in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Find the spreadsheet named Q3 budget in my Google Sheets, list its sheet names, then read the first 50 rows of the main sheet and summarize what is in it.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Google Sheets is connected in the dashboard, that agent calls the same 40 Google Sheets tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Google Sheets MCP for Hermes

Looking for a Google Sheets MCP server for Hermes Agent? ClawLink connects Google Sheets to Hermes Agent and exposes 40 Google Sheets tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Google Sheets integration](https://claw-link.dev/openclaw/google-sheets) runs on the same hosted Google provider and the same 40 tools; OpenClaw installs ClawLink through a ClawHub skill instead of the Hermes pairing commands.

Asked how to do this, the current answers hand Hermes users a Google Cloud shopping list: a project, the Sheets and Drive APIs enabled by hand, a Desktop-type OAuth client, a client-secret JSON downloaded to the machine running Hermes. ClawLink's route has none of those parts. Pair Hermes once, click Connect next to Google Sheets in the dashboard, approve the two permissions on Google's own consent screen, and the 40 tools below answer from your next message. No service account exists in this flow, so no sheet ever needs sharing with a robot email.

## What the Hermes Agent Google Sheets integration can do

40 Google Sheets tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 40.

### 30 of 40 Google Sheets tools for Hermes

| Tool | What it does |
|---|---|
| **Add sheet** `googlesheets_add_sheet` | Add a new sheet to a spreadsheet |
| **Aggregate column data** `googlesheets_aggregate_column_data` | Aggregate column data by matching and computing |
| **Batch get** `googlesheets_batch_get` | Retrieve data from multiple cell ranges |
| **Clear values** `googlesheets_clear_values` | Clear cell content from a range |
| **Create chart** `googlesheets_create_chart` | Create a chart in a Google Sheet |
| **Create google sheet1** `googlesheets_create_google_sheet1` | Create a new Google Spreadsheet |
| **Create spreadsheet column** `googlesheets_create_spreadsheet_column` | Create a new column in a Google Sheet |
| **Create spreadsheet row** `googlesheets_create_spreadsheet_row` | Insert a new row into a Google Sheet |
| **Find replace** `googlesheets_find_replace` | Find and replace text across cells |
| **Format cell** `googlesheets_format_cell` | Apply text and background formatting to cells |
| **Get data validation rules** `googlesheets_get_data_validation_rules` | Get data validation rules from a spreadsheet |
| **Get sheet names** `googlesheets_get_sheet_names` | List all worksheet names in a spreadsheet |
| **Get spreadsheet info** `googlesheets_get_spreadsheet_info` | Get metadata for a Google Spreadsheet |
| **Lookup spreadsheet row** `googlesheets_lookup_spreadsheet_row` | Find a row by exact cell content match |
| **Search spreadsheets** `googlesheets_search_spreadsheets` | Search for Google Spreadsheets by name or content |
| **Set data validation rule** `googlesheets_set_data_validation_rule` | Set data validation rules or dropdowns on a range |
| **Spreadsheets sheets copy to** `googlesheets_spreadsheets_sheets_copy_to` | Copy a sheet to another spreadsheet |
| **Spreadsheets values append** `googlesheets_spreadsheets_values_append` | Append values to the end of a Google Sheet |
| **Spreadsheets values batch clear** `googlesheets_spreadsheets_values_batch_clear` | Clear values from multiple ranges at once |
| **Update sheet properties** `googlesheets_update_sheet_properties` | Update sheet tab properties like name or color |
| **Update spreadsheet properties** `googlesheets_update_spreadsheet_properties` | Update spreadsheet-level properties like title or locale |
| **Update values batch** `googlesheets_update_values_batch` | Update values in multiple ranges at once |
| **Upsert rows** `googlesheets_upsert_rows` | Upsert rows by key column, appending or updating |
| **Values get** `googlesheets_values_get` | Read values from a range in a Google Sheet |
| **Values update** `googlesheets_values_update` | Update values in a range of a Google Sheet |
| **Get conditional format rules** `googlesheets_get_conditional_format_rules` | List conditional formatting rules for each sheet (or a selected sheet) in a normalized |
| **Get spreadsheet by data filter** `googlesheets_get_spreadsheet_by_data_filter` | Returns the spreadsheet at the given ID, filtered by the specified data filters |
| **Search developer metadata** `googlesheets_search_developer_metadata` | Search for developer metadata in a spreadsheet |
| **Spreadsheets values batch get by data filter** `googlesheets_spreadsheets_values_batch_get_by_data_filter` | Return one or more ranges of values from a spreadsheet that match the specified data filters |
| **Append dimension** `googlesheets_append_dimension` | Append new rows or columns to a sheet, increasing its size |

## Example prompts

**Read and summarize**

> Find the spreadsheet named Q3 budget in my Google Sheets, list its sheet names, then read the first 50 rows of the main sheet and summarize what is in it.

**Append rows**

> Append these rows to the end of the Expenses sheet in that spreadsheet, using USER_ENTERED so the dates and amounts arrive as typed values rather than text.

**Build a weekly digest**

> Every value in column A of my Tracker sheet is a project name. Read the sheet, group the rows by status, and give me a short digest of what moved this week.

**Recover from a missing id**

> If a Sheets call fails saying spreadsheet_id is required, search my spreadsheets by name first and retry the same call with the real id from the search results instead of asking me.

## What the Google Sheets tools actually expect

The argument rules behind most of the Sheets failures we log, from the live schemas and our own error rows.

- **Tools take the spreadsheet ID, never the name.** It is the long string between `/d/` and `/edit` in the sheet's URL, and the missing id is the most common real Sheets failure in ClawLink logs. Paste the URL into chat or have the agent call `googlesheets_search_spreadsheets` first.
- **The id argument's casing changes between tools.** `values_get`, `values_update` and `batch_get` take `spreadsheet_id`; `spreadsheets_values_append` and `update_sheet_properties` take `spreadsheetId`. An agent reusing arguments across calls sees `arguments.spreadsheetId is required` with no hint that only the casing moved.
- **`value_input_option` is required on writes:** `USER_ENTERED` parses like typing (dates, numbers, live formulas), `RAW` stores exact strings. 107 logged calls failed just by omitting it. Appends additionally take `insertDataOption`, either `OVERWRITE` or `INSERT_ROWS`.
- **Ranges are A1 notation with the exact sheet title in front**, single-quoted when it contains spaces (`'Monthly budget'!A1:C10`). Wrong titles fail with the literal `Invalid sheet identifier or cell reference provided.`; `googlesheets_get_sheet_names` returns the real ones.
- **`values` is an array of arrays, one inner array per row.** Flat arrays fail validation before the request reaches Google.
- **The read tool is `googlesheets_values_get`,** and invented names like `googlesheets_get_values` fail with a not-found error that lists the closest real tools; the suggestion is almost always right.
- **`googlesheets_search_spreadsheets` is a Drive API call** with Drive query syntax (`name contains 'budget'`, `fullText contains 'sales'`), and it is the first tool to break if the Drive permission was unticked on the consent screen.
- **Google's documented Sheets read quota is 60 requests per minute per user.** Per-cell loops hit 429 (`Too many requests. Try again shortly.`); `googlesheets_batch_get` and `googlesheets_update_values_batch` do the same work in one call. Wait and retry on a 429; do not reconnect.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Google Sheets working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Google Sheets app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Google Sheets through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Google Sheets. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Google Sheets actions to the runtime in a format your agent can reliably use. | 40 tools for Google Sheets are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Google Sheets to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Google Sheets in the browser, and the 40 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Google Sheets
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Google Sheets from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Google Sheets tools
Google Sheets tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Google Sheets call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Google Sheets returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### "arguments.spreadsheet_id is required" (or "arguments.spreadsheetId is required") from Google Sheets
The agent used the sheet's name where a tool needed its id, and both spellings of the message are real because the casing differs per tool. Paste the sheet's URL into the chat, or have the agent run `googlesheets_search_spreadsheets` with a name query and retry with the id it returns. This is the most common real Sheets failure we log, well ahead of anything Google-side.

### "arguments.value_input_option is required" when updating a Google Sheet
The update tool refuses to guess between its two modes. `USER_ENTERED` parses input like typing, so dates and formulas come alive; `RAW` stores literal strings. Say which one you want in the prompt; `USER_ENTERED` is right for most real data. This omission accounts for 107 logged failures on its own.

### "Invalid sheet identifier or cell reference provided" from Google Sheets
The sheet title in the range does not exist in that spreadsheet, or the A1 reference is malformed. Titles are matched exactly and need single quotes when they contain spaces. Have Hermes call `googlesheets_get_sheet_names` and build the range from a returned title rather than assuming `Sheet1`.

### "Tool 'googlesheets_get_values' not found" and other missing Google Sheets tools
If the error suggests alternatives, the agent invented a tool name and the suggestion (`googlesheets_values_get` for reads) is the fix. If Sheets tools are missing wholesale, the runtime's catalog is stale: reconnect from the dashboard and start a fresh chat. Ignore advice about deleting `token.json` or restarting a server process; a hosted connection has neither.

### "Request had insufficient authentication scopes" (403) when searching Sheets while reads still work
The Google grant behind the connection is missing its Drive permission. ClawLink asks for spreadsheets and Drive, each with its own checkbox on Google's consent screen, and a connection approved without the Drive box behaves exactly like this: reads by id succeed, search by name fails. Reconnect from the dashboard and leave every checkbox ticked.

### "Connected account is not in an ACTIVE state. Current status is REVOKED" from Google Sheets
Access was withdrawn on the Google side, by you under Third-party apps and services or by a workspace admin. Reconnect Google Sheets from the ClawLink dashboard and approve the consent screen again, then start a fresh chat so Hermes picks the connection up.

### OAuth finished in the browser but the account is still missing
Try reconnecting Google Sheets and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent Google Sheets integration?
Yes. ClawLink is the fastest way to connect Hermes to Google Sheets: link your Google Sheets account once in the browser and Hermes Agent can call the Google Sheets API through 40 ready-made tools — no custom code or token handling.

### How do I connect Google Sheets to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Google Sheets in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect Google Sheets to Hermes Agent?
About two minutes. Sign in, click Connect next to Google Sheets in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Google Sheets up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Google Sheets working from chat.

### Do I need a Google Cloud project or my own OAuth app to connect Google Sheets to Hermes?
No. The Cloud project, the two APIs you enable by hand, the Desktop OAuth client, the client-secret JSON: all of that is the price of the self-hosted route, and it is what most guides walk you through because they assume no one else can own the OAuth app. ClawLink owns a verified one. Pairing Hermes and clicking Connect is the entire setup, and no credential file ever lands on the machine running Hermes.

### Do I need to share my sheet with a service account email?
No. Sharing a sheet with a `client_email` is service-account advice, and there is no service account anywhere in this flow. The connection signs in as your Google account and sees what you see. When a call fails with a 403 despite a healthy connection, check the spreadsheet id the agent sent before touching any sharing settings; an invented or copied-from-an-example id is the usual culprit.

### Which Google permissions does the Sheets connection request?
`https://www.googleapis.com/auth/spreadsheets` and `https://www.googleapis.com/auth/drive`, plus your email to label the connection, verified against a live connection rather than quoted from a catalog. Drive is in the list because searching spreadsheets by name or content is a Drive API operation. Each permission gets its own checkbox on Google's consent screen, and both need to stay ticked for every tool to work. Revoking is one click in your Google account's Third-party apps and services page or in the ClawLink dashboard.

### Is it safe to connect Google Sheets to an AI agent?
Judge it by the mechanics rather than assurances. Google's consent screen lists exactly what is granted; the tool table on this page is the complete set of operations an agent can invoke; there is no API key or JSON file to leak because none exists. Revocation works instantly from your Google account or the dashboard, and ClawLink deletes tool execution logs after 90 days. The lever that matters most is yours: connect an account that only sees what the agent should, and lean on Sheets version history for anything write-heavy.

### Hermes paired but still can't use Google Sheets
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [Hermes Google Super integration](https://claw-link.dev/hermes/google-super) — Unified access to multiple Google services in one integration
- [Google Drive](https://claw-link.dev/hermes/google-drive) — Upload, search, and manage files
- [Google Analytics](https://claw-link.dev/hermes/google-analytics) — Connect Google Analytics properties through hosted Google OAuth