@waleedyousaf07/mcp-google-sheets

Thin Google Sheets MCP server for any MCP-compatible client. It runs over stdio, uses direct Google Sheets + Drive REST calls, and keeps the tool surface small.

Quick Start

npx @waleedyousaf07/mcp-google-sheets@latest

OAuth Setup

Create a Google OAuth Desktop app, enable the Google Sheets API and Google Drive API, and use one of:

MCP_GOOGLE_SHEETS_CLIENT_ID=your_client_id
MCP_GOOGLE_SHEETS_CLIENT_SECRET=your_client_secret

Or point to the downloaded OAuth JSON file:

MCP_GOOGLE_SHEETS_CLIENT_CREDENTIALS_PATH=/absolute/path/to/google-oauth-client.json

Optional:

MCP_GOOGLE_SHEETS_USE_KEYTAR=true

If MCP_GOOGLE_SHEETS_USE_KEYTAR=true but keytar is unavailable, the server falls back to a plaintext token file in the OS config directory.

Scopes

This package uses:

• https://www.googleapis.com/auth/spreadsheets
• https://www.googleapis.com/auth/drive.metadata.readonly

That covers reading/writing Sheets content plus metadata-based discovery in My Drive.

Reference Resolution

All spreadsheet-targeting tools accept exactly one reference field:

• id
• url
• name
• path (My Drive style like Folder/Subfolder/FileName)

If a name or path lookup resolves to 0 or multiple spreadsheets, the tool returns an error with candidate metadata.

Tools

• sheets.searchSpreadsheets
• sheets.getSpreadsheet
• sheets.createSpreadsheet
• sheets.getValues
• sheets.batchGetValues
• sheets.updateValues
• sheets.appendValues
• sheets.clearValues
• sheets.batchUpdate

Client Config Example

Any MCP client that can launch a stdio server can use this package. Use npx as the default command so the config stays portable across macOS, Linux, and Windows:

{
  "id": "google-sheets",
  "transport": "stdio",
  "command": [
    "npx",
    "--yes",
    "@waleedyousaf07/mcp-google-sheets@latest"
  ],
  "headers": {}
}

If your MCP client supports OS-specific overrides, only add a Windows-specific npx.cmd path there. Keep the default config on plain npx.

Troubleshooting

• Browser did not open: the server prints the Google auth URL to stderr. Open it manually in a browser on the same machine. This is expected on headless Linux or any machine without a desktop opener.
• invalid_grant: your stored refresh token is no longer valid. Delete the saved token from your user config directory and authorize again.
• Permission errors: confirm the Google Sheets and Google Drive APIs are enabled in your Google Cloud project and the OAuth client is a Desktop app.

Local Commands

pnpm i
pnpm build
pnpm test
node dist/cli.js