Google Sheets MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Google Sheets, enabling AI agents to read, search, and intelligently modify spreadsheet data.

Features

• 📊 Read spreadsheet data by file, sheet, or specific range

• ✏️ Smart cell updates with partial text replacement

• 🔍 Search and filter capabilities across sheets

• 📝 Preserve formatting and formulas during updates

• 🔐 Secure OAuth 2.0 authentication

• ⚡ Batch operations for efficient bulk updates

• 🛡️ Type-safe with full TypeScript support

Quick Start

Prerequisites

• Node.js 18+

• Google Cloud Project with Sheets API enabled

• OAuth 2.0 credentials from Google Cloud Console

Installation

npm install

Configuration

1. Enable Google Sheets API

   • Go to Google Cloud Console

   • Create a new project or select existing one

   • Enable "Google Sheets API" and "Google Drive API"

   • Create OAuth 2.0 credentials (Desktop app)

2. Set up environment variables

Create a .env file:

# Google OAuth 설정
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback

# 서비스 계정 설정 (선택사항)
GOOGLE_SERVICE_ACCOUNT_KEY_PATH=./path/to/service-account-key.json

3. Start the MCP server

# Development
npm run dev

# Production
npm run build
npm start

4. Install the MCP server

# add this to mcp.json etc.
"google-sheets-mcp-server": {
      "command": "node",
      "args": ["YOUR_PATH/google-sheets-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID":"YOUR_CLIENT_ID",
        "GOOGLE_CLIENT_SECRET":"YOUR_CLIENT_SECRET",
        "GOOGLE_REDIRECT_URI":"http://localhost:3000/oauth/callback",
        "NODE_ENV":"development",
        "LOG_LEVEL":"info"
      }
    }

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Available Tools

Read Tools

• sheets_list_files - List accessible spreadsheets

• sheets_list_sheets - List sheets in a spreadsheet

• sheets_read_data - Read all data from a sheet

• sheets_read_range - Read data from a specific range

• sheets_search - Search for text in cells

Update Tools

• sheets_update_cell - Update a single cell

• sheets_update_range - Update multiple cells

• sheets_smart_replace - Smart text replacement

• sheets_append_rows - Add new rows

Management Tools

• sheets_create_sheet - Create a new sheet

• sheets_delete_sheet - Delete a sheet

• sheets_rename_sheet - Rename a sheet

Documentation

• API Reference - Complete tool documentation

• Tutorials - Step-by-step guides

• Contributing - How to contribute

Features

• ✅ OAuth 2.0 Authentication - Secure Google account integration

• ✅ Service Account Support - For automated workflows

• ✅ Smart Text Replacement - Partial text updates with context preservation

• ✅ Batch Operations - Efficient bulk updates

• ✅ Error Handling - Comprehensive error management with retry logic

• ✅ Rate Limiting - Built-in API quota management

• ✅ Type Safety - Full TypeScript support

• ✅ Comprehensive Testing - Unit and integration tests

Performance

• Read operations: < 2 seconds for sheets up to 10,000 cells

• Write operations: < 5 seconds for batches up to 1,000 cells

• Smart replace: < 3 seconds for sheets up to 5,000 cells

• Rate limiting: 60 requests per minute by default

Security

• OAuth tokens stored securely using system keychain

• All API communications use HTTPS

• No sensitive data logged

• Read-only mode available for sensitive spreadsheets

• Input validation and sanitization

License

MIT