MCP Gsheet

🚀 MCP Google Sheets Server

This project offers a Model Context Protocol (MCP) server that enables interaction with Google Sheets.

It provides the following capabilities:

• List worksheets (tabs) in a spreadsheet.
• Read data from a specific cell range.
• Write data to a specific cell range.

It does not offer tools for managing Google Drive files (listing, creating, deleting files/folders). Access is restricted to spreadsheet content.

🚀 Quick Start

✨ Features

• List worksheets in a spreadsheet.
• Read data from a specific cell range.
• Write data to a specific cell range.

📦 Installation

Prerequisites

1. Python 3.11+
2. A Google Cloud project with the Google Sheets API enabled
3. Service account key:
   • Go to the Google Cloud Console to create a new service account.
   • Download the service account key file (in JSON format).
   • Grant the "Editor" role to this service account for accessing the target spreadsheet.

Steps

1. Clone the repository.

   git clone https://github.com/shionhonda/mcp-gsheet.git
   

2. Set up Google credentials:
   • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the absolute path of the downloaded service account key file.

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
   

   • Alternatively, place the key file in the standard location recognized by the Google Cloud client library (not recommended for shared environments).
3. Install dependencies:

   uv venv
   source .venv/bin/activate
   

4. Run the server
   • Use the MCP checker development server:

   mcp dev server.py
   

   • Run the server:

   mcp run server.py
   

   The server will start and listen for MCP requests on standard input/output (stdio).

💻 Usage Examples

Basic Usage

In your Claude Desktop configuration, add the following content:

{
  "mcpServers": {
    "gsheet": {
      "command": "/path/to/uv",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
      },
      "args": ["--directory", "/path/to/mcp-gsheet", "run", "server.py"]
    }
  }
}

📚 Documentation

MCP Tools' Capabilities

• list_sheets(spreadsheet_id: str) -> list[str]: List the names of all worksheets in the specified spreadsheet.
• read_cells(spreadsheet_id: str, range_name: str) -> list[list[str]]: Read data from the given range (e.g., 'Sheet1!A1:B5').
• write_cells(spreadsheet_id: str, range_name: str, values: list[list[str]]) -> str: Write the provided two - dimensional string list to the specified starting cell/range (e.g., 'Sheet1!C1').