google-sheets-mcp
MCP server for Google Sheets - read, write, and query spreadsheet data.
Use Cases
Data questions: "How many open deals are in the pipeline?" or "What's our total Q3 revenue?" → reads the spreadsheet and answers directly.
Quick expense entry: Snap a photo of a receipt → extracts the details and appends a row to your expense tracker.
Cross-tool status sync: "Check all our vendor Slack channels and update the tracking spreadsheet with their latest updates" → reads Slack, updates the sheet.
Data analysis: "Break down the Salesforce figures by region and compare against our events calendar" → pulls data from multiple sources into a spreadsheet for analysis.
(These are just examples - any workflow that needs spreadsheet data can use this. Use in combination with google-drive-mcp for finding files, deleting, comments, and sharing permissions.)
Setup
1. Create Google OAuth credentials
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable the Google Sheets API
- Go to APIs & Services → OAuth consent screen, set up consent screen
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Choose Web application
- Add
http://localhost:3000/callback to Authorized redirect URIs
- Note your Client ID and Client Secret
2. Run the server
GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start
The server runs on http://localhost:3000 by default. Change with PORT=3001.
3. Add to your MCP client
With the server running, follow the instructions on install-mcp, which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).
Architecture
This server acts as an OAuth proxy to Google:
graph LR
A[MCP client] <--> B[google-sheets-mcp] <--> C[Google OAuth/API]
- Server advertises itself as an OAuth authorization server via
/.well-known/oauth-authorization-server
/register returns the Google OAuth client credentials/authorize redirects to Google, encoding the client's callback URL in state/callback receives the code from Google and forwards to the client's callback/token proxies token requests to Google, injecting client credentials/mcp handles MCP requests, using the bearer token to call Google Sheets API
The server holds no tokens or state - it just proxies OAuth to Google.
| Tool | Description |
|---|
| Spreadsheet | |
sheets_spreadsheet_get | Get spreadsheet metadata (title, sheets list, optionally cell data) |
sheets_spreadsheet_create | Create a new spreadsheet |
| Values | |
sheets_values_get | Read cell values from a range |
sheets_values_batch_get | Read cell values from multiple ranges |
sheets_values_update | Write cell values to a range (overwrites) |
sheets_values_batch_update | Write cell values to multiple ranges |
sheets_values_append | Append rows after existing data |
sheets_values_clear | Clear cell values from a range |
| Sheets (tabs) | |
sheets_sheets_list | List all sheets in a spreadsheet |
sheets_sheet_add | Add a new sheet (tab) |
sheets_sheet_delete | Delete a sheet (tab) |
| Advanced | |
sheets_batch_update | Execute batch operations (formatting, merging, filters, etc.) |
Google Sheets API Scope
spreadsheets - Full read/write access to spreadsheets
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install
- Run
npm run test to run tests
- Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch> to bump the version
- Run
git push --follow-tags to push with tags
- Wait for GitHub Actions to publish to the NPM registry.