MCP Google Sheets Server

For the most user-friendly approach, you can provide just the private key and email directly. This is the simplest method and requires only two fields from your service account JSON:

{ "mcpServers": { "mcp-gsheets": { "command": "npx", "args": ["-y", "mcp-gsheets@latest"], "env": { "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n", "GOOGLE_CLIENT_EMAIL": "[email protected]" } } } }

- Newlines in the private key should be represented as\\n
- The private key must include the-----BEGIN PRIVATE KEY-----and-----END PRIVATE KEY-----markers
- The client email should be the service account email from your JSON file
- GOOGLE_PROJECT_IDis optional when using this method

If you want to develop or contribute to this project, you can clone and build it locally:

# Clone the repository git clone https://github.com/freema/mcp-gsheets.git cd mcp-gsheets # Install dependencies npm install # Build the project npm run build

Run the interactive setup script to configure your local MCP client:

- Guide you through the configuration
- Automatically detect your Node.js installation (including nvm)
- Find your Claude Desktop config
- Create the proper JSON configuration
- Optionally create a .env file for development

If you prefer manual configuration with a local build, add to your MCP client config:

{ "mcpServers": { "mcp-gsheets": { "command": "node", "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"], "env": { "GOOGLE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json" } } } }

# Development mode with hot reload npm run dev # Build for production npm run build # Type checking npm run typecheck # Clean build artifacts npm run clean # Run MCP inspector for debugging npm run inspector # Run MCP inspector in development mode npm run inspector:dev

# Install dependencies task install # Build the project task build # Run in development mode task dev # Run linter task lint # Format code task fmt # Run all checks task check

cp .env.example .env # Edit .env with your credentials: # GOOGLE_PROJECT_ID=your-project-id # GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json # TEST_SPREADSHEET_ID=your-test-spreadsheet-id

npm run dev # Watch mode with auto-reload

All 44 tools together cost about9,900 tokens of context in every session, before the model does anything. Most workflows need a fraction of that.GSHEETS_TOOLSETSlimits which tools the server exposes:

{ "mcpServers": { "gsheets": { "command": "npx", "args": ["mcp-gsheets"], "env": { "GOOGLE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json", "GSHEETS_TOOLSETS": "core,charts" } } } }

- The default is unchanged— leaveGSHEETS_TOOLSETSunset and you get every tool, exactly as before.
- coreis always included.GSHEETS_TOOLSETS=chartsmeans "charts as well as core", not "charts only" — without core the server cannot read a cell.
- A typo is a startup error, not a silently smaller tool list.
- GSHEETS_READ_ONLY=truedrops every writing tool and can be combined withGSHEETS_TOOLSETS. It is enforced when a tool is called, not just when the list is built, so a client cannot write by naming a hidden tool.

All tools also carry MCP annotations (readOnlyHint,destructiveHint,idempotentHint), so clients can skip confirmation prompts on reads and warn before destructive operations.

# Run ESLint npm run lint # Fix auto-fixable issues npm run lint:fix

# Check formatting with Prettier npm run format:check # Format code npm run format

# Run TypeScript type checking npm run typecheck

- If using file-based auth: Verify JSON key path is absolute and correct
- If using JSON string auth: Ensure JSON is properly escaped and valid
- If using private key auth: Check that the private key includes BEGIN/END markers and newlines are escaped as\\n
- Verify GOOGLE_CLIENT_EMAIL is a valid service account email
- Check GOOGLE_PROJECT_ID matches your project (or is included in JSON for full JSON auth)
- Ensure Sheets API is enabled

- Share spreadsheet with service account email
- Service account needs "Editor" role
- Check email in JSON file (client_email field)

- Verify spreadsheet ID from URL
- Format:https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

- Ensure you're using the built version (dist/index.js)
- Check that Node.js path is correct in Claude Desktop config
- Look for errors in Claude Desktop logs
- Usenpm run inspectorto debug

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit ↑ This is the spreadsheet ID

Usesheets_get_metadatato list all sheets with their IDs.
- Always test with a copy of your data
- Use batch operations for better performance
- Set appropriate permissions (read-only vs edit)
- Check rate limits for large operations
- Usesheets_check_accessto verify permissions before operations

Returns lightweight structural/dimensional metadata for a sheet without any per-cell data. Much faster and cheaper thansheets_get_full_sheet_snapshotwhen you only need layout information.

- spreadsheetId(required): The ID of the spreadsheet
- sheetName(required): Name of the sheet (tab)

Returns:sheetName,sheetId,sheetIndex,tabColor,tabColorStyle,dimensions(rowCount,columnCount),frozen(rowCount,columnCount),columnWidths(array of pixel sizes),rowHeights(array of pixel sizes),hiddenColumns(0-based indices),hiddenRows(0-based indices),mergeCount,merges(A1 notation array)

Read cell formatting for a range and return it as compact A1Range → format pairs. Adjacent cells with identical formatting are collapsed into rectangular ranges (run-length encoded), reducing output by 90 %+ compared to per-cell data.

- spreadsheetId(required): The ID of the spreadsheet
- sheetName(required): Name of the sheet (tab)
- range(required): Range without sheet prefix, e.g."A1:Z85"
- useEffectiveFormat(optional):false(default) = userEnteredFormat (only explicit overrides, smaller output);true= effectiveFormat (all inherited defaults)
- fields(optional): Array of format field names to include, e.g.["backgroundColor", "textFormat", "borders"]

Returns:{ range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

Supported fields:backgroundColor,backgroundColorStyle,textFormat,horizontalAlignment,verticalAlignment,wrapStrategy,textRotation,numberFormat,padding,borders

Master one-shot tool that returns all structural and formatting metadata in a single API call.

- spreadsheetId(required): The ID of the spreadsheet
- sheetName(required): Name of the sheet (tab)
- includeFormattingRange(optional): If provided (e.g."A1:Z100"), per-cell formatting is included in the response
- useEffectiveFormat(optional): Use effectiveFormat instead of userEnteredFormat when including cell formatting (default:false)
- fields(optional): Array of format field names to return, e.g.["backgroundColor", "textFormat"]— reduces API transfer size and response size
- compactMode(optional): Whentrue, identical adjacent cells are collapsed into rectangular ranges (RLE). Reduces a typical 85×28 sheet from ~60 000 lines to ~500 lines (default:false)

Insert new rows at a specific position in a spreadsheet with optional data.

- spreadsheetId(required): The ID of the spreadsheet
- range(required): A1 notation anchor point where rows will be inserted (e.g., "Sheet1!A5")
- rows(optional): Number of rows to insert (default: 1)
- position(optional): 'BEFORE' or 'AFTER' the anchor row (default: 'BEFORE')
- inheritFromBefore(optional): Whether to inherit formatting from the row before (default: false)
- values(optional): 2D array of values to fill the newly inserted rows
- valueInputOption(optional): 'RAW' or 'USER_ENTERED' (default: 'USER_ENTERED')

// Insert 1 empty row before row 5 { "spreadsheetId": "your-spreadsheet-id", "range": "Sheet1!A5" } // Insert 3 rows after row 10 with data { "spreadsheetId": "your-spreadsheet-id", "range": "Sheet1!A10", "rows": 3, "position": "AFTER", "values": [ ["John", "Doe", "[email protected]"], ["Jane", "Smith", "[email protected]"], ["Bob", "Johnson", "[email protected]"] ] }

Delete one or more columns from a sheet using a full-column A1 range.

- spreadsheetId(required): The ID of the spreadsheet
- range(required): Full-column A1 range to delete (e.g., "Sheet1!B:D" or "Sheet1!C:C")

// Delete columns B through D from Sheet1 { "spreadsheetId": "your-spreadsheet-id", "range": "Sheet1!B:D" } // Delete a single column from the first sheet { "spreadsheetId": "your-spreadsheet-id", "range": "C:C" }

Delete one or more rows from a sheet using a full-row A1 range.

- spreadsheetId(required): The ID of the spreadsheet
- range(required): Full-row A1 range to delete (e.g., "Sheet1!2:4" or "Sheet1!3:3")

// Delete rows 2 through 4 from Sheet1 { "spreadsheetId": "your-spreadsheet-id", "range": "Sheet1!2:4" } // Delete a single row from the first sheet { "spreadsheetId": "your-spreadsheet-id", "range": "3:3" }

SeeCHANGELOG.mdfor a list of changes in each version.
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Run tests and linting (npm run check)
- Commit your changes (git commit -m 'Add some amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

This project is licensed under the MIT License - see the[LICENSEfile for details.

Interact with Google Sheets using a Python-based MCP server and Google Apps Script.

Full Google Sheets integration - read, write, format cells, create charts, use formulas, and manage spreadsheets.

Parses invoice data, uploads it to Google Sheets, and answers queries by fetching information from the sheet.

A data firewall between AI and your Google Sheets - Integrate with Google Sheets to read, write, and manage spreadsheet data.

A specialized Google Sheets integration server that allows the LLM to read, write, and manage spreadsheet data in real-time. This server supports cell-level manipulation, bulk range updates, and full worksheet retrieval, enabling the model to perform data analysis, logging, and automated reporting directly within Google Worksheets.If you have functions which take range value then first read the sheet and decide where user is asking to add data and define range by your own.Provides 46 tools for Gsheet