Google Sheet MCP Server

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.