Google Sheet MCP Server

An MCP (Model Context Protocol) server that allows AI agents to read, write, and manage Google Sheets using the Google Sheets API v4.

Features

• List Sheets: Retrieve a list of all sheets in a spreadsheet with their names, IDs, and grid properties.
• Read Content: Read data from specific sheets or ranges, returned as formatted Markdown tables.
• Write Content: API to create sheets, append data, and add columns.
• Manage Structure: Rename sheets and delete sheets, columns, or rows.

Prerequisites

• Python: 3.12 or higher
• Package Manager: uv (recommended) or pip
• Google Cloud Project:
• "Google Sheets API" enabled.
• Service Account created with a JSON key file.
• Access: The Service Account email MUST have "Editor" access to the target Google Sheet to perform write operations.

Getting service-account-key.json

1. Create Project: Go to Google Cloud Console and create a new project.
2. Enable API: Search for "Google Sheets API" and click Enable.
3. Create Service Account:

• Go to IAM & Admin > Service Accounts.
• Click Create Service Account.
• Name it (e.g., sheet-mcp-bot) and click Create and Continue.
• Grant "Editor" role, then click Done.

1. Generate Key:

• Click on the newly created Service Account email.
• Go to the Keys tab > Add Key > Create new key.
• Select JSON and click Create.
• The file will download automatically. Rename it to service-account-key.json.

1. Share Sheet: Open your target Google Sheet, click Share, and paste the Service Account email (found in the JSON file under client_email) with Editor permissions.

Installation

1. Clone/Open this repository.
2. Install dependencies:

    uv sync
    # or
    pip install mcp pandas python-dotenv google-api-python-client google-auth

Configuration

1. Service Account: Place your Google Service Account JSON key in the project root and name it service-account-key.json (or update .env to point to its path).
2. Environment Variables: Create a .env file:

    SPREADSHEET_ID=your_spreadsheet_id_here
    SERVICE_ACCOUNT_FILE=service-account-key.json

Tip: The Spreadsheet ID is the long string in your sheet's URL: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`

Usage with MCP Clients

Option 1: Using uvx (Recommended)

This method allows you to run the server directly from GitHub without cloning the repository manually.

Add this configuration to your MCP settings file (e.g., claude_desktop_config.json or mcp_config.json):

{
  "mcpServers": {
    "google-sheet": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/vfh-tech/gsheet-mcp",
        "sheet-mcp"
      ],
      "env": {
        "SPREADSHEET_ID": "your_spreadsheet_id_here",
        "SERVICE_ACCOUNT_FILE": "C:\\path\\to\\your\\service-account-key.json"
      }
    }
  }
}

Option 2: Local Installation

If you prefer to clone the repository and run it locally:

{
  "mcpServers": {
    "google-sheet": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sheet-mcp",
        "run",
        "sheet-mcp"
      ],
      "env": {
        "SPREADSHEET_ID": "your_spreadsheet_id_here",
        "SERVICE_ACCOUNT_FILE": "service-account-key.json"
      }
    }
  }
}

Testing

A verification script is included to test the connection and tools:

uv run test_server.py

Tools Available

Read Operations

• list_sheets(): Lists all sheets in the configured spreadsheet.
• read_sheet_data(sheet_name: str, range_name: str = None, last_20_rows: bool = False): Reads data from the specified sheet. Set last_20_rows=True to read only the last 20 rows (plus header).

Write Operations

• create_sheet(title: str): Creates a new sheet (tab).
• rename_sheet(old_title: str, new_title: str): Renames an existing sheet.
• append_data(sheet_name: str, values: List[List[Any]]): Appends rows of data to the bottom of a sheet.
• add_column(sheet_name: str, header: str, values: List[Any] = None): Adds a new column to the right of the existing data, with an optional header and values.

Delete Operations (Destructive)

• delete_sheet(sheet_name: str): Deletes an entire sheet.
• delete_row(sheet_name: str, start_index: int, end_index: int): Deletes rows within a specified range.
• delete_column(sheet_name: str, start_index: int, end_index: int): Deletes columns within a specified range.