mcp-gsheets — Claude Code MCP server for Google Sheets
Connects Google Sheets API to your agent: read and write cells, format ranges, run batch operations.
claude mcp add --env GOOGLE_PROJECT_ID=<GOOGLE_PROJECT_ID> --env GOOGLE_APPLICATION_CREDENTIALS=<GOOGLE_APPLICATION_CREDENTIALS> --env GOOGLE_SERVICE_ACCOUNT_KEY=<GOOGLE_SERVICE_ACCOUNT_KEY> --env GOOGLE_PRIVATE_KEY=<GOOGLE_PRIVATE_KEY> --env GOOGLE_CLIENT_EMAIL=<GOOGLE_CLIENT_EMAIL> --transport stdio mcp-gsheets -- npx -y mcp-gsheetsWhat mcp-gsheets does
The server gives your agent direct access to Google Sheets. Read data from ranges, write values, apply formatting and conditional formatting, work with charts. Batch operations let you update hundreds of rows in one call.
Requires Node.js 22 or higher and a Google Cloud service account with Sheets API enabled. Three authentication methods are supported: JSON key file, full JSON string, or private key plus email pair. You need to share spreadsheets with the service account email and grant editor permissions — without this the server won't have access.
Built with TypeScript, includes error handling and test coverage.
What it helps with
- Read data from cell ranges
- Write and update values in batch
- Apply formatting and conditional rules
- Create charts in spreadsheets
- Fetch sheet and workbook metadata
Example prompts for the agent
- Read range A1:D50 from spreadsheet with ID 1a2b3c4d5e
- Write these rows to the Sales sheet starting at cell B2
- Format column C as currency with two decimal places
How to install mcp-gsheets
Platform CLI
claude mcp add --env GOOGLE_PROJECT_ID=<GOOGLE_PROJECT_ID> --env GOOGLE_APPLICATION_CREDENTIALS=<GOOGLE_APPLICATION_CREDENTIALS> --env GOOGLE_SERVICE_ACCOUNT_KEY=<GOOGLE_SERVICE_ACCOUNT_KEY> --env GOOGLE_PRIVATE_KEY=<GOOGLE_PRIVATE_KEY> --env GOOGLE_CLIENT_EMAIL=<GOOGLE_CLIENT_EMAIL> --transport stdio mcp-gsheets -- npx -y mcp-gsheetsReplace <…> with your own values
Platform CLI
codex mcp add mcp-gsheets --env GOOGLE_PROJECT_ID=<GOOGLE_PROJECT_ID> --env GOOGLE_APPLICATION_CREDENTIALS=<GOOGLE_APPLICATION_CREDENTIALS> --env GOOGLE_SERVICE_ACCOUNT_KEY=<GOOGLE_SERVICE_ACCOUNT_KEY> --env GOOGLE_PRIVATE_KEY=<GOOGLE_PRIVATE_KEY> --env GOOGLE_CLIENT_EMAIL=<GOOGLE_CLIENT_EMAIL> -- npx -y mcp-gsheetsReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-gsheets": {
"command": "npx",
"args": [
"-y",
"mcp-gsheets"
],
"env": {
"GOOGLE_PROJECT_ID": "<GOOGLE_PROJECT_ID>",
"GOOGLE_APPLICATION_CREDENTIALS": "<GOOGLE_APPLICATION_CREDENTIALS>",
"GOOGLE_SERVICE_ACCOUNT_KEY": "<GOOGLE_SERVICE_ACCOUNT_KEY>",
"GOOGLE_PRIVATE_KEY": "<GOOGLE_PRIVATE_KEY>",
"GOOGLE_CLIENT_EMAIL": "<GOOGLE_CLIENT_EMAIL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-gsheets": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-gsheets"
],
"env": {
"GOOGLE_PROJECT_ID": "<GOOGLE_PROJECT_ID>",
"GOOGLE_APPLICATION_CREDENTIALS": "<GOOGLE_APPLICATION_CREDENTIALS>",
"GOOGLE_SERVICE_ACCOUNT_KEY": "<GOOGLE_SERVICE_ACCOUNT_KEY>",
"GOOGLE_PRIVATE_KEY": "<GOOGLE_PRIVATE_KEY>",
"GOOGLE_CLIENT_EMAIL": "<GOOGLE_CLIENT_EMAIL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GOOGLE_PROJECT_ID=<GOOGLE_PROJECT_ID> -e GOOGLE_APPLICATION_CREDENTIALS=<GOOGLE_APPLICATION_CREDENTIALS> -e GOOGLE_SERVICE_ACCOUNT_KEY=<GOOGLE_SERVICE_ACCOUNT_KEY> -e GOOGLE_PRIVATE_KEY=<GOOGLE_PRIVATE_KEY> -e GOOGLE_CLIENT_EMAIL=<GOOGLE_CLIENT_EMAIL> mcp-gsheets npx -y mcp-gsheetsReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-gsheets
How to install mcp-gsheets in Claude Code?
Run `claude mcp add mcp-gsheets -e GOOGLE_PROJECT_ID=<GOOGLE_PROJECT_ID> -e GOOGLE_SERVICE_ACCOUNT_KEY=<GOOGLE_SERVICE_ACCOUNT_KEY> -e GOOGLE_PRIVATE_KEY=<GOOGLE_PRIVATE_KEY> -- npx -y mcp-gsheets`, substituting your environment variable values.
What does mcp-gsheets do?
Integrates Google Sheets API into your agent: read, write, and format cells, run batch updates, work with charts and conditional formatting.
What credentials are needed?
You need a Google Cloud project with Sheets API enabled and a service account. Pass the JSON key file path via GOOGLE_APPLICATION_CREDENTIALS, or the full JSON in GOOGLE_SERVICE_ACCOUNT_KEY, or just the private key and email via GOOGLE_PRIVATE_KEY and GOOGLE_CLIENT_EMAIL.
