sheets-mcp-server

An MCP server that lets AI agents read and write Google Sheets. Built with the Model Context Protocol and the Google Sheets API v4.

Tools

Tool	Description
sheets_read	Read data from a range in a Google Sheet
sheets_write	Write a 2D array of values to a range
sheets_append	Append rows to the end of a sheet
sheets_create	Create a new spreadsheet with custom tabs
sheets_info	Get spreadsheet metadata (title, sheets, dimensions)
sheets_format	Apply bold, background color, or text color to a range

Setup

1. Create a Google Cloud project

1. Go to the Google Cloud Console.
2. Click Select a project > New Project.
3. Give it a name and click Create.

2. Enable the Google Sheets API

1. In the Cloud Console, go to APIs & Services > Library.
2. Search for Google Sheets API and click Enable.

3. Create a service account

1. Go to APIs & Services > Credentials.
2. Click Create Credentials > Service account.
3. Give it a name (e.g. sheets-mcp) and click Done.
4. Click the new service account, go to the Keys tab.
5. Click Add Key > Create new key > JSON and download the file.
6. Save the JSON key file somewhere secure (e.g. ~/.config/sheets-mcp/service-account.json).

4. Share your spreadsheets

Open any Google Sheet you want the server to access, click Share, and add the service account email address (found in the JSON key file under client_email). Grant Editor access.

5. Set the environment variable

export GOOGLE_SERVICE_ACCOUNT_KEY=/path/to/service-account.json

Or create a .env file in the project directory:

GOOGLE_SERVICE_ACCOUNT_KEY=/path/to/service-account.json

Installation

# With pip
pip install .

# Or with uv
uv pip install .

Claude Desktop configuration

Add this to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "sheets": {
      "command": "sheets-mcp",
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

Or if running from the source directory with uv:

{
  "mcpServers": {
    "sheets": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sheets-mcp", "sheets-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

Example usage

Once connected, an AI agent can use the tools like this:

Read data:

Read cells A1 through D10 from spreadsheet 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

Write data:

Write these sales figures to Sheet1!A1:C3: [["Product", "Q1", "Q2"], ["Widget", 150, 230], ["Gadget", 320, 180]]

Create a new spreadsheet:

Create a new spreadsheet called "Project Tracker" with tabs "Tasks", "Timeline", and "Budget"

Format headers:

Bold the header row A1:E1 and give it a blue background (#4285F4) with white text (#FFFFFF)

Append rows:

Append these new entries to the bottom of the log in Sheet1: [["2026-03-13", "Completed review", "Alice"]]

License

MIT