@slv-npm/google-sheets-mcp-server

MCP server that gives AI agents full access to Google Sheets — read, write, format, search, and manage spreadsheets.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent.

Quick Start

npx @slv-npm/google-sheets-mcp-server setup

1. Your browser opens → log in with Google → authorize
2. Choose your agent (Claude Code, Cursor, etc.)
3. Done. Restart your agent and start using Google Sheets.

No Google Cloud Console setup required.

What It Can Do

| Tool | Description | |------|-------------| | sheets_get_spreadsheet | Get spreadsheet metadata (title, tabs, dimensions) | | sheets_create_spreadsheet | Create a new spreadsheet | | sheets_add_sheet | Add a new sheet/tab | | sheets_delete_sheet | Delete a sheet/tab | | sheets_duplicate_sheet | Duplicate a sheet/tab | | sheets_read_range | Read cell values (A1 notation) | | sheets_write_range | Write values to a range | | sheets_append_rows | Append rows after existing data | | sheets_clear_range | Clear values (keeps formatting) | | sheets_batch_read | Read multiple ranges in one call | | sheets_batch_write | Write to multiple ranges in one call | | sheets_batch_update | Formatting, merge, sort, borders, conditional formatting… | | sheets_find_in_sheet | Search for a value in a range |

Usage Examples

Once configured, just talk to your agent:

"Read the data from my spreadsheet 1BxiM... sheet Sales"

"Add a row with Alice, [email protected], 95 to my tracking sheet"

"Make the header row bold with a gray background"

"Find all cells containing 'overdue' in the Tasks sheet"

Manual Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@slv-npm/google-sheets-mcp-server"]
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@slv-npm/google-sheets-mcp-server"]
    }
  }
}

Config location: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Linux ~/.config/Claude/claude_desktop_config.json

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@slv-npm/google-sheets-mcp-server"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@slv-npm/google-sheets-mcp-server"]
    }
  }
}

Authentication

OAuth2 (default)

The setup wizard handles everything — just log in with Google. Tokens are stored in ~/.config/google-sheets-mcp/ and refresh automatically.

Service Account (servers / CI)

For headless environments, use a Service Account:

npx @slv-npm/google-sheets-mcp-server setup
# → Choose "Service Account key file"

Or set the environment variable directly:

"env": { "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json" }

HTTP mode

For Claude.ai or remote agents:

npx @slv-npm/google-sheets-mcp-server --http
# → http://127.0.0.1:3100/mcp

Environment Variables

| Variable | Description | |----------|-------------| | GOOGLE_SERVICE_ACCOUNT_KEY_FILE | Path to Service Account JSON key | | GOOGLE_SERVICE_ACCOUNT_KEY | Inline JSON key (Docker / CI) | | TRANSPORT | stdio (default) or http | | PORT | HTTP port (default: 3100) |

Re-authorize

To switch Google accounts or fix auth issues:

rm ~/.config/google-sheets-mcp/oauth-tokens.json
npx @slv-npm/google-sheets-mcp-server setup

Development

git clone https://github.com/user/google-sheets-mcp-server.git
cd google-sheets-mcp-server
npm install
npm run build
node dist/index.js --help

License

MIT