Google Sheets MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to interact with Google Sheets for reading, writing, and creating spreadsheets.

Features

• read_sheet: Read data from specific ranges in Google Sheets
• write_sheet: Write data to specific cells
• create_sheet: Create new spreadsheets
• Secure authentication with Service Account
• Robust input validation and error handling
• ES modules support
• TypeScript support

Installation

Via npm (Recommended)

npm install -g google-sheets-mcp-server

From source

git clone https://github.com/jorge-espinosa/google-sheets-mcp-server.git
cd google-sheets-mcp-server
npm install

Setup

1. Google Cloud Setup

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select an existing one

2. Enable APIs:

   • Enable Google Sheets API
   • Enable Google Drive API

3. Create Service Account:

   • Go to IAM & Admin > Service Accounts
   • Create a new service account
   • Download the credentials JSON file
   • Rename it to credentials.json and place it in your project root

2. Environment Configuration

1. Copy the environment file:

cp .env.example .env

2. Configure your Spreadsheet ID:

   • Edit .env file
   • Replace your_spreadsheet_id_here with your actual Google Sheets ID
   • The Spreadsheet ID can be found in the URL: https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

3. Build the project (if installing from source):

npm run build

Permissions Setup

To use the server with existing spreadsheets, share the spreadsheet with your service account email (found in your credentials.json file) and assign "Editor" permissions.

Usage

Running the Server

Development

npm run dev

Production

npm start

Global Installation

google-sheets-mcp

Available Scripts

• npm run build - Compile TypeScript
• npm run dev - Run in development mode
• npm run start - Run compiled server
• npm run test - Run basic functionality test

Claude Desktop Integration

Add this to your Claude Desktop config file:

{
  "mcpServers": {
    "google-sheets": {
      "command": "google-sheets-mcp",
      "args": [],
      "env": {
        "GOOGLE_SHEETS_SPREADSHEET_ID": "your_spreadsheet_id_here"
      }
    }
  }
}

Important: Replace your_spreadsheet_id_here with your actual Google Sheets ID.

MCP Tools

read_sheet

Reads data from a specific range in a spreadsheet.

Parameters:

• spreadsheetId (string): Spreadsheet ID
• range (string): Range to read (e.g., "Sheet1!A1:C10")

Usage example:

{
  "name": "read_sheet",
  "arguments": {
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range": "Sheet1!A1:C10"
  }
}

write_sheet

Writes data to a specific range in a spreadsheet.

Parameters:

• spreadsheetId (string): Spreadsheet ID
• range (string): Range to write to (e.g., "Sheet1!A1")
• values (array): 2D array of values to write

Usage example:

{
  "name": "write_sheet",
  "arguments": {
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range": "Sheet1!A1",
    "values": [
      ["Name", "Age", "City"],
      ["John", "25", "Madrid"],
      ["Ana", "30", "Barcelona"]
    ]
  }
}

create_sheet

Creates a new spreadsheet.

Parameters:

• title (string): Title of the new spreadsheet

Usage example:

{
  "name": "create_sheet",
  "arguments": {
    "title": "My New Spreadsheet"
  }
}

Project Structure

├── src/
│   ├── index.ts      # Main MCP server
│   ├── auth.ts       # Google authentication
│   └── validation.ts # Input validation
├── credentials.json  # Service Account credentials
├── package.json
├── tsconfig.json
└── README.md

Limitations

• Maximum 10,000 cells per write operation
• Sheet titles limited to 100 characters
• Requires sharing permissions for existing sheets
• Subject to Google Sheets API quota limits

Troubleshooting

Authentication Error

• Verify credentials.json is in the project root
• Verify APIs are enabled in Google Cloud Console

Permission Error

• Share the sheet with the service account email
• Verify the spreadsheet ID is correct

Range Format Error

• Use correct format: "SheetName!A1:C10"
• Verify the sheet name is correct

Contributing

To contribute to the project:

1. Fork the repository
2. Create a feature branch
3. Implement changes with validation
4. Run tests before committing
5. Create a pull request

License

MIT