Sheets MCP

Give Claude Desktop the ability to read, write, and manage Google Sheets — directly in conversation.

---

Overview

Claude has no built-in way to talk to Google Sheets. Sheets MCP is a small local server that sits between Claude Desktop and the Google Sheets/Drive APIs, speaking the Model Context Protocol so Claude can call it like any other tool.

Ask Claude things like:

"List my Google Sheets" "Read A1:D10 from my Budget spreadsheet" "Add a row to my Tasks sheet with today's date and 'Follow up with client'"

...and it actually happens, live, in your real spreadsheet.

How it works

 You  <──chat──>  Claude Desktop  <──MCP (stdio)──>  Sheets MCP server  <──REST──>  Google Sheets / Drive API

Claude Desktop starts the server locally, sends it tool calls over stdio, and the server translates those into real Google API requests using a saved OAuth login.

Tools

Tool	Description	Required arguments
list_sheets	Find spreadsheets by name	query (optional)
read_range	Read cell values from a range	spreadsheetId, range
write_range	Overwrite cell values in a range	spreadsheetId, range, values
append_row	Add row(s) to the end of a sheet	spreadsheetId, sheetName, values

The spreadsheetId is the long string in a sheet's URL, between /d/ and /edit:

https://docs.google.com/spreadsheets/d/1XUqH2AumsmusdvsavsdvadsvewrvVAFAvEMcWzUmrlg/edit
                                       └──────────── spreadsheetId ─────────────┘

In practice you can just ask Claude in plain English (e.g. "read my Budget sheet") and it'll use list_sheets to find the ID for you — you don't have to paste it yourself.

Prerequisites

• Node.js 18 or newer
• Claude Desktop already installed
• A Google account with access to the Sheets you want Claude to use

Setup

0. Clone this repo

git clone https://github.com/Luchitha7/sheets-mcp.git
cd sheets-mcp

1. Create Google OAuth credentials

All of this happens in Google Cloud Console, logged into the Google account you want Claude to access sheets as.

1. Create a project — top-left project dropdown → New Project → name it (e.g. sheets-mcp) → Create, then make sure it's selected as the active project.
2. Enable two APIs — use the top search bar to find and enable, one at a time:
   • Google Sheets API
   • Google Drive API (needed so the server can look up a spreadsheet by name, not just by ID)
3. Set up the consent screen — left sidebar → Google Auth Platform → Branding (older docs may call this "OAuth consent screen," it's the same thing).
   • User type: External (unless you're on a Google Workspace org)
   • Fill in app name + your email, click through the wizard (Audience, Contact Information, Finish)
   • On the Audience page, scroll to Test users → Add users → add your own Google account email. Skip this and Google will block your login later with an access_denied error, since unpublished apps only allow pre-approved accounts to sign in.
4. Create the OAuth Client ID — left sidebar → Clients → Create OAuth client
   • Application type: Desktop app (not "Web application" — a desktop app client is built for a local script doing its own login, not a website with a public redirect URL)
   • Name it anything, e.g. Sheets MCP Desktop, click Create
5. Download the credentials — a popup shows a Client ID and Client Secret. If clicking "Download JSON" there doesn't produce a file (a known quirk), instead go to Clients → click your new client → use the download icon next to Client secret on its detail page.
6. Save the downloaded file as credentials/gcp-oauth-client.json in this project.

2. Install dependencies

npm install

3. Log in to Google (one-time)

npm run auth

This opens your browser to log in and grant access, then saves a token to credentials/token.json. You won't need to log in again unless access is revoked.

4. Connect it to Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config, and add this server under mcpServers (keep any existing entries in the file):

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

Fully quit and reopen Claude Desktop. sheets-mcp should now appear under Settings → Developer → Local MCP servers.

Project structure

sheets-mcp/
├── server.js         # The MCP server — exposes the 4 tools to Claude
├── auth.js           # Shared OAuth login + token refresh logic
├── auth-setup.js      # One-time login script (npm run auth)
├── credentials/       # gcp-oauth-client.json + token.json (gitignored)
└── package.json

Troubleshooting

Symptom	Cause	Fix
access_denied during login	App is in "Testing" mode	Add your Google account under Audience → Test users
Drive API has not been used...	Drive API not enabled on the project	Enable it in Google Cloud Console, wait a minute, retry
Server missing from Claude Desktop	Config not picked up	Fully quit and reopen Claude Desktop (not just close the window)
Login expired / revoked	Token no longer valid	Rerun npm run auth

Security notes

• credentials/gcp-oauth-client.json and credentials/token.json contain secrets and are gitignored — never commit or share them.
• The server only requests the minimum scopes needed: read/write Sheets, and read-only Drive metadata (to list files).

License

MIT