Skip to content
Back to search

gsheets-session-mcp

MCP server to read, write, and diff a Google Sheet via your existing Chrome session (no OAuth/API key/GCP project), using an unpacked extension acting in an open Sheets tab.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hatemosphere--gsheets-session-mcp/badge.svg)](/listings/hatemosphere--gsheets-session-mcp)

HTML

<a href="/listings/hatemosphere--gsheets-session-mcp"><img src="/api/listings/hatemosphere--gsheets-session-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install dependencies:

   pnpm install

2. Config is optional. There is no spreadsheet ID in config - tools target the open tab by URL/ID. The only setting is `activity` limits; create `secrets.local.json` from the template only if you want to change them:

   {
     "activity": {
       "maxEvents": 200,
       "maxChangesPerEvent": 500,
       "maxMemoryMb": 8
     }
   }

Omitted fields use those defaults. Memory is measured as approximate UTF-8 JSON size, not V8 heap overhead. The save session (sid/rev/reqId) is held in memory per spreadsheet and needs no config. 3. Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**, and select the `extension/` directory. Keep the extension enabled. After updating files in `extension/`, use the extension's **Reload** button so Chrome drops its cached script version. 4. Keep the sheet(s) you want to work with open in that Chrome profile. No reload is needed for tabs that were already open; the extension injects its tab client on demand. Any open Sheets tab can be targeted by URL/ID. 5. Register the MCP server with your client as before, pointing at the absolute path of `server.mjs` (for example `node /path/to/server.mjs`).

When the Google session expires, sign in to Chrome and reload the sheet. The bridge reconnects automatically and the MCP keeps working without editing the config or recapturing a request.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 221 lines
  1. # gsheets-session MCP
  2. Read, write, inspect selections, and compare revision versions of a Google Sheet
  3. using your **existing Chrome session**. No OAuth client, API key, GCP project, or
  4. repeated cookie capture. This works for sheets shared with a visitor-session
  5. (invite-only) non-Google account, where the v4 Sheets API is not available.
  6. An unpacked Chrome extension performs reads and saves inside an open Sheets tab.
  7. Google cookies and session tokens stay in the browser; the MCP process sees only
  8. sheet data and commands over a loopback-only WebSocket.
  9. Targeting is dynamic. Every tool takes an optional `spreadsheet` (a full Sheets
  10. URL or a bare spreadsheet ID) and optional `gid`. If you omit them and exactly
  11. one Sheets tab is open, that tab is used; if several are open, the call errors and
  12. lists them so you can pick one. `list_sheets` returns every open Sheets tab. There
  13. is no per-sheet config: open the sheet in Chrome and address it by URL/ID.
  14. ## How it works
  15. ```mermaid
  16. flowchart LR
  17. mcp[stdio MCP] <-->|127.0.0.1:17834| ext[Chrome extension]
  18. ext <-->|tab messages| sheet[Open Sheets tab]
  19. sheet <-->|session cookies| google[docs.google.com]
  20. ```
  21. - **Reads:** the tab requests gviz CSV (`/gviz/tq`), which uses the browser's
  22. current session cookies.
  23. - **Writes:** the MCP builds the existing `/save` mutation bundles; the tab adds
  24. fresh `info_params` (`token`, `ouid`) and POSTs the same-origin request. The
  25. server's operational transform preserves concurrent edits elsewhere.
  26. - **Selections:** the tab reads the active A1 range from the name box and visible
  27. collaborator presence. Values for that range are fetched through gviz.
  28. - **Revision list:** the tab fetches the editor's `/revisions/tiles` JSON;
  29. timestamps, authors, revision ranges, and version names are mapped in Node.
  30. - **Revision diff:** full revision snapshots are fetched and parsed into cell maps;
  31. the MCP returns only changed cells as `{cell, before, after, kind}`.
  32. - **Activity:** the extension captures `/streamrows` request bodies via
  33. `webRequest`, batches them per sheet and `snapshotAt`, and sends the URL/body to
  34. the MCP. The MCP replays each request inside the tab and decodes the response
  35. into changed cells (`lib/streamrows.mjs`). It appends decoded channel values
  36. under `event.channel` and still uses revision diffs for exact before/after values
  37. and authors.
  38. There is no official Sheets API path for this setup: the API requires OAuth, and
  39. live selection plus version-history cell snapshots are not exposed through it.
  40. The implementation avoids UI automation and reads only these narrow tab values.
  41. ## Setup
  42. 1. Install dependencies:
  43. ```
  44. pnpm install
  45. ```
  46. 2. Config is optional. There is no spreadsheet ID in config - tools target the
  47. open tab by URL/ID. The only setting is `activity` limits; create
  48. `secrets.local.json` from the template only if you want to change them:
  49. ```json
  50. {
  51. "activity": {
  52. "maxEvents": 200,
  53. "maxChangesPerEvent": 500,
  54. "maxMemoryMb": 8
  55. }
  56. }
  57. ```
  58. Omitted fields use those defaults. Memory is measured as approximate UTF-8 JSON
  59. size, not V8 heap overhead. The save session (sid/rev/reqId) is held in memory
  60. per spreadsheet and needs no config.
  61. 3. Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**,
  62. and select the `extension/` directory. Keep the extension enabled. After
  63. updating files in `extension/`, use the extension's **Reload** button so Chrome
  64. drops its cached script version.
  65. 4. Keep the sheet(s) you want to work with open in that Chrome profile. No reload
  66. is needed for tabs that were already open; the extension injects its tab client
  67. on demand. Any open Sheets tab can be targeted by URL/ID.
  68. 5. Register the MCP server with your client as before, pointing at the absolute
  69. path of `server.mjs` (for example `node /path/to/server.mjs`).
  70. When the Google session expires, sign in to Chrome and reload the sheet. The
  71. bridge reconnects automatically and the MCP keeps working without editing the
  72. config or recapturing a request.
  73. ## Tools
  74. All tools except `list_sheets` accept an optional `spreadsheet` (URL or ID) and
  75. optional `gid`; omit them to use the single open Sheets tab.
  76. | Tool | Input | Output |
  77. | --- | --- | --- |
  78. | `list_sheets` | `{}` | open Sheets tabs: `{spreadsheetId, gid, title, url, active}` |
  79. | `read_range` | `{spreadsheet?, gid?, range?}` | `{rows: string[][]}` from gviz |
  80. | `write_cells` | `{spreadsheet?, gid?, edits: [{a1, value}]}` | `{written, rev}`; atomic save |
  81. | `clear_cells` | `{spreadsheet?, gid?, cells: [a1]}` | `{written, rev}`; writes empty strings |
  82. | `get_selection` | `{spreadsheet?, gid?, includeValues?}` | active range, up to 2000 cell values, viewers with status |
  83. | `list_revisions` | `{spreadsheet?, limit?}` | newest-first versions with timestamp, authors, range, name |
  84. | `diff_revisions` | `{spreadsheet?, gid?, fromRevision, toRevision, range?, maxChanges?}` | structured cell changes and summary |
  85. | `get_activity` | `{spreadsheet?, limit?, since?}` | in-memory live activity events with revision, authors, and cell changes |
  86. `get_selection` example:
  87. ```json
  88. {
  89. "range": "A2",
  90. "selectionBy": "current-tab",
  91. "viewers": [{ "name": "Jordan Lee", "status": "inactive", "label": "Jordan Lee (inactive)" }],
  92. "values": [["Date"]]
  93. }
  94. ```
  95. `list_revisions` entries use the end revision as the version identifier:
  96. ```json
  97. {
  98. "revision": 71,
  99. "range": { "start": 37, "end": 71 },
  100. "timestamp": "2026-11-03T09:07:04.682Z",
  101. "authors": ["Jordan Lee", "sam.carter@example.com"],
  102. "name": null,
  103. "expandable": true
  104. }
  105. ```
  106. Pass those revisions to `diff_revisions`; results are ordered by row then column:
  107. ```json
  108. {
  109. "summary": { "changed": 4, "added": 2, "removed": 2, "returned": 4, "truncated": false },
  110. "changes": [
  111. { "kind": "removed", "cell": "H3", "before": "Old task", "after": null },
  112. { "kind": "added", "cell": "H5", "before": null, "after": "Onboarding: accounts" },
  113. { "kind": "changed", "cell": "I5", "before": "4", "after": "8" }
  114. ]
  115. }
  116. ```
  117. Use `range` to limit a large diff and `maxChanges` to cap the returned list while
  118. keeping full counts in `summary`.
  119. `get_activity` returns events accumulated while the MCP is running. Poll it with
  120. the previous newest event's `time` as `since`:
  121. ```json
  122. {
  123. "tracking": { "YOUR_SPREADSHEET_ID": 259 },
  124. "total": 1,
  125. "limits": { "maxEvents": 200, "maxChangesPerEvent": 500, "maxMemoryMb": 8, "maxMemoryBytes": 8388608 },
  126. "sizeBytes": 612,
  127. "events": [{
  128. "time": "2026-11-03T12:10:21.604Z",
  129. "spreadsheetId": "YOUR_SPREADSHEET_ID",
  130. "revision": 259,
  131. "fromRevision": 258,
  132. "authors": ["sam.carter@example.com", "Jordan Lee"],
  133. "summary": { "changed": 1, "added": 1, "removed": 0, "returned": 1, "truncated": false },
  134. "changes": [{ "kind": "added", "cell": "K1", "before": null, "after": "activity-trigger-probe" }]
  135. }]
  136. }
  137. ```
  138. `tracking` maps each monitored spreadsheet ID to its last-seen revision. Pass
  139. `spreadsheet` to `get_activity` to filter the log to one sheet.
  140. ## Limits / caveats
  141. - **Strings and numbers only** for writes. Native formula edits use a separate
  142. structured formula/token payload; writing `=1+1` through the string value type
  143. stores literal text, not a formula. Values beginning with `=` are rejected.
  144. - **Clearing** writes `""`, which reads as blank but is not a true content-delete.
  145. - **Selection scope:** only the local tab's selected range is stable. Collaborator
  146. presence names/status are returned, but live remote cursor ranges are not exposed
  147. by a stable interface. A local selection larger than 2000 cells omits `values`;
  148. call `read_range` for it.
  149. - **Revision diffs** compare displayed cell values, not formatting, comments, or
  150. charts. Revision snapshots can be large; diffs are capped by `maxChanges`.
  151. - **Activity is in-memory and best-effort.** It is bounded by `activity.maxEvents`
  152. (default 200), `activity.maxChangesPerEvent` (default 500), and
  153. `activity.maxMemoryMb` (default 8 MB of approximate serialized JSON). Old entries
  154. are evicted first; an oversized event is trimmed and dropped if its metadata
  155. alone cannot fit. The log resets when the MCP restarts. Edits made while MCP or the extension is disconnected are not
  156. logged; query `list_revisions`/`diff_revisions` for the full history. It includes
  157. MCP-originated writes too. Tracking is per spreadsheet across all open tabs; the
  158. exact before/after diff uses the gid of that sheet's open tab (falling back to
  159. `0`), so on a multi-tab document, changes on a sheet other than the open tab's
  160. may appear only under `channel` without a full cell diff.
  161. - **Author attribution is revision-level.** Authors come from the covering version
  162. tile and can include several people; this is not per-cell blame.
  163. - **Undocumented endpoints.** Google can change `/save`, `/revisions/tiles`, or
  164. `/revisions/show`. Reads already have a public-ish gviz fallback; writes and
  165. history may need protocol updates if Google changes the editor.
  166. - **Security:** the bridge listens only on `127.0.0.1:17834` and accepts WebSocket
  167. origins beginning with `chrome-extension://`. It does not accept web-page origins.
  168. The extension's `webRequest` listener is restricted to Sheets URLs. It observes
  169. StreamRows request bodies (URL and form fields), then replays them in the tab;
  170. it does not expose browser cookies or response bodies on the bridge.
  171. - **Startup order.** The MCP is the WebSocket server, so the extension can only
  172. connect once the MCP is running. The extension only attempts to connect while a
  173. Sheets tab is open and retries with backoff, so it links up automatically when
  174. the MCP starts. If Chrome has a sheet open before the MCP is up, Chrome logs one
  175. or more `net::ERR_CONNECTION_REFUSED` lines on `ws://127.0.0.1:17834` in the
  176. extension's error panel; these are the browser's own logs of the refused socket
  177. (the extension cannot suppress them), they are harmless, and they stop once the
  178. MCP is running. Start the MCP before opening the sheet to avoid them entirely.
  179. ## Files
  180. - `server.mjs` - stdio MCP and tool implementations
  181. - `lib/bridge.mjs` - loopback WebSocket bridge and request queue
  182. - `lib/activity.mjs` - bounded in-memory activity store and limits
  183. - `lib/encode.mjs` - `/save` mutation encoder
  184. - `lib/target.mjs` - parse a Sheets URL or ID into `{spreadsheetId, gid}`
  185. - `lib/streamrows.mjs` - StreamRows response decoder for observed cell changes
  186. - `extension/` - unpacked Chrome MV3 extension
  187. - `save-write.mjs` - **legacy** standalone writer; it still uses captured
  188. `cookie`/`token` fields directly and is separate from the MCP path
  189. - `test-encode.mjs` - encoder regression test
  190. - `test-target.mjs` - sheet URL/ID parser test
  191. - `test-activity.mjs` - activity cap, trimming, memory, and filtering test
  192. - `test-streamrows.mjs` - StreamRows decoder regression test
  193. Run the offline tests with `pnpm test`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.