berni23/mcp-google-sheets

MCP Google Sheets Server

A Model Context Protocol (MCP) server that provides Google Sheets integration. This server enables reading, writing, and appending data to Google Sheets through MCP tools.

Features

• Read Sheet: Read values from a Google Sheet range
• Write Sheet: Write values to a specific Google Sheet range
• Append Sheet: Append new rows to a Google Sheet
• Create plot Create a plot from a dataset in a Google Sheet

Prerequisites

• Python 3.10 or higher
• Google Cloud Service Account with Sheets API access
• Service account credentials JSON file

Setup

Option 1: Using uv (recommended)

1. Install dependencies:

   uv sync
   

Option 2: Using pip

1. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

Google Sheets API Setup

1. Set up Google Sheets API:

   • Create a Google Cloud Project
   • Enable the Google Sheets API
   • Create a Service Account
   • Download the service account credentials JSON file
   • Rename it to credentials.json and place it in the project root

2. Share your Google Sheet:

   • Share your Google Sheet with the service account email address
   • Grant "Editor" permissions

Usage

Run the MCP server:

python server.py

The server will start and listen for MCP requests via stdio.

MCP Tools

read_sheet

Read values from a Google Sheet.

Parameters:

• spreadsheet_id (str): The Google Sheet ID
• range_ (str): The range to read (e.g., "A1:C10", "Sheet1!A:Z")

Returns: List of rows, each row is a list of cell values.

write_sheet

Write values to a Google Sheet range.

Parameters:

• spreadsheet_id (str): The Google Sheet ID
• range_ (str): The range to write to
• values (list[list[Any]]): 2D array of values to write

Returns: Google Sheets API response object.

append_sheet

Append new rows to a Google Sheet.

Parameters:

• spreadsheet_id (str): The Google Sheet ID
• range_ (str): The range to append to
• values (list[list[Any]]): 2D array of values to append

Returns: Google Sheets API response object.

Configuration

The server uses service account authentication. Place your credentials.json file in the project root directory.

Required scopes:

• https://www.googleapis.com/auth/spreadsheets

Dependencies

• fastmcp: Fast MCP server framework
• google-api-python-client: Google Sheets API client
• google-auth: Google authentication libraries

License

MIT License