MCP GSheets

MCP Google Sheets Server

A Model Context Protocol (MCP) server for Google Sheets API integration. Enables reading, writing, and managing Google Sheets documents directly from your MCP client (e.g., Claude Code, Claude Desktop, Cursor, etc.).

Key Features

• Complete Google Sheets Integration: Read, write, and manage spreadsheets
• Advanced Operations: Batch operations, formatting, charts, and conditional formatting
• Flexible Authentication: Support for both file-based and JSON string credentials
• Production Ready: Built with TypeScript, comprehensive error handling, and full test coverage

Requirements

• Node.js v22 or higher
• Google Cloud Project with Sheets API enabled
• Service Account with JSON key file
• npm

Getting Started

Quick Install (Recommended)

Add the following config to your MCP client:

{

"mcpServers": { "mcp-gsheets": { "command": "npx", "args": ["-y", "mcp-gsheets@latest"], "env": { "GOOGLE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json" } } } }

[!NOTE]

Using mcp-gsheets@latest ensures that your MCP client will always use the latest version of the MCP Google Sheets server.

MCP Client Configuration

Claude Code Use the Claude Code CLI to add the MCP Google Sheets server ( guide ):

claude mcp add mcp-gsheets npx mcp-gsheets@latest

After adding, edit your Claude Code config to add the required environment variables:

{

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

Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{

"mcpServers": { "mcp-gsheets": { "command": "npx", "args": ["-y", "mcp-gsheets@latest"], "env": { "GOOGLE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json" } } } }

Cursor

Go to Cursor Settings → MCP → New MCP Server. Use the config provided above.

Cline

Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.

Other MCP Clients

For other MCP clients, use the standard configuration format shown above. Ensure the command is set to npx and include the environment variables for Google Cloud authentication.

Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google Sheets API:

• Navigate to "APIs & Services" → "Library"
• Search for "Google Sheets API" and click "Enable"

1. Create Service Account:

• Go to "APIs & Services" → "Credentials"
• Click "Create Credentials" → "Service Account"
• In the service accounts list, click the three dots in the Actions column → Manage keys → Add key → Create new key → select JSON format
• Download the JSON key file

1. Share your spreadsheets:

• Open your Google Sheet
• Click Share and add the service account email (from JSON file)
• Grant "Editor" permissions

Alternative Authentication Methods

Option 1: JSON String Authentication

Instead of using a file path for credentials, you can provide the service account credentials directly as a JSON string. This is useful for containerized environments, CI/CD pipelines, or when you want to avoid managing credential files.

{

"mcpServers": { "mcp-gsheets": { "command": "npx", "args": ["-y", "mcp-gsheets@latest"], "env": { "GOOGLE_PROJECT_ID": "your-project-id", "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]\\n\",\"client_email\":\"...@....iam.gserviceaccount.com\",\"client_id\":\"...\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"...\"}" } } } }

Note: When using GOOGLE_SERVICE_ACCOUNT_KEY:

• The entire JSON must be on a single line
• All quotes must be escaped with backslashes
• Newlines in the private key must be represented as \\n
• If the JSON includes a project_id, you can omit GOOGLE_PROJECT_ID

Option 2: Private Key Authentication (Simplified)

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": "[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]\\n", "GOOGLE_CLIENT_EMAIL": "spreadsheet@your-project.iam.gserviceaccount.com" } } } }

Note: When using GOOGLE_PRIVATE_KEY:

• Newlines in the private key should be represented as \\n
• The private key must include the [PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก] markers
• The client email should be the service account email from your JSON file
• GOOGLE_PROJECT_ID is optional when using this method

Local Development Setup

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

Interactive Setup Script

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

npm run setup

This will:

• 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

Manual Local Configuration

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" } } } }

📦 Build & Development

Development Commands

# 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

Task Runner (Alternative)

If you have Task installed:

# 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

Development Setup

1. Create .env file for testing:

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

1. Run in development mode:

npm run dev  # Watch mode with auto-reload

🎚️ Reducing context cost with toolsets

All 44 tools together cost about 9,900 tokens of context in every session, before the model does anything. Most workflows need a fraction of that. GSHEETS_TOOLSETS limits 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" } } } }

Measured tools/list cost:

Notes:

• The default is unchanged — leave GSHEETS_TOOLSETS unset and you get every tool, exactly as before.
• `core` is always included. GSHEETS_TOOLSETS=charts means "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=true drops every writing tool and can be combined with GSHEETS_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.

📋 Available Tools

Reading Data

Writing Data

|