MCP Google Sheets Server

How to use

You connect to the MCP Google Sheets Server from your MCP client and then call the available tool endpoints to interact with your Google Sheets documents. Use it to read data, write updates, format cells, manage sheets, and create charts without leaving your MCP environment. Start by configuring a single stdio MCP server that runs locally via a command like npx and points to the latest version of the MCP Google Sheets server.

How to install

Prerequisites you need before starting: Node.js version 18 or higher and npm. You also need a Google Cloud project with the Sheets API enabled and a service account key in JSON format.

# 1) Ensure Node.js v18+ is installed
node -v

# 2) Create a project directory for your MCP client configuration (optional)
mkdir my-mcp-config
cd my-mcp-config

# 3) Add the MCP Google Sheets server to your client configuration (example config)
{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}
```

A quick way to ensure you always run the latest MCP Google Sheets server is to use the `mcp-gsheets@latest` tag in the config above.

Prerequisites and setup steps

Follow these steps to set up Google Sheets authentication and enable access to your spreadsheets.

1) Create or select a Google Cloud project and enable Google Sheets API in APIs & Services. 2) Create a Service Account in IAM & Admin and download the JSON key file. 3) Share each target spreadsheet with the service account email found in the JSON file and grant Editor permissions.

4) Place the JSON key file somewhere accessible to your MCP client and set the environment variables in your MCP client config as shown in the quick install snippet above.

Alternative authentication methods

If you prefer not to rely on a file path for credentials, you can use a JSON string or simplified private key authentication. When using a JSON string, provide the full service account JSON as a single line and escape all quotes and newlines appropriately in your environment variable. If you opt for private key authentication, provide only the private key and the service account email.

Notes on environment variables

The core setup uses these environment variables: - GOOGLE_PROJECT_ID: Your Google Cloud project identifier - GOOGLE_APPLICATION_CREDENTIALS: Absolute path to the service account JSON key If you choose the JSON string or private key methods, you would use the corresponding variables (as shown in the alternative authentication section) instead.

Security considerations

Keep your service account key secure. Do not commit credentials to source control. When using JSON strings or private keys, ensure they are stored in secure secret stores or vaults in your deployment environment.

Troubleshooting

If you encounter authentication or permission issues, verify that: - The Google Sheets API is enabled for your project. - The service account email from the JSON key is shared with the target spreadsheets with Editor permissions. - The GOOGLE_PROJECT_ID matches your Google Cloud project (or is included in the JSON for full JSON authentication). - The path to the credentials file is absolute and accessible by the process running the MCP server.

Available operations overview

The server exposes a comprehensive set of endpoints to read from, write to, format, and manage Google Sheets. Core categories include: - Reading data (values, metadata, access checks) - Writing data (values, inserts, appends, clears) - Sheet management (insert/delete/duplicate sheets, copy to other spreadsheets) - Batch operations (batch deletes, batch formats) - Cell formatting and borders - Conditional formatting - Chart creation and updates

Common usage patterns

- Read a range to validate existing data before performing updates. - Append new rows to a sheet when collecting new records. - Insert rows at a specific position to preserve formatting. - Format cells to highlight important data or apply consistent styling. - Create charts to visualize data directly from MCP-driven workflows.

sheets_get_values

Read values from a specified spreadsheet range.

sheets_batch_get_values

Read values from multiple ranges in a single call.

sheets_get_metadata

Retrieve spreadsheet metadata, including sheet names and IDs.

sheets_check_access

Verify access permissions for the current user/service account.

sheets_update_values

Write values to a specified range in a spreadsheet.

sheets_batch_update_values

Update values across multiple ranges in a single operation.

sheets_append_values

Append rows to a table with options to control insertion behavior.

sheets_clear_values

Clear contents of specified cells.

sheets_insert_rows

Insert new rows at a specific position with optional data.

sheets_insert_sheet

Add a new sheet to a spreadsheet.

sheets_delete_sheet

Remove a sheet from a spreadsheet.

sheets_duplicate_sheet

Create a copy of an existing sheet.

sheets_copy_to

Copy a sheet or range to another spreadsheet.

sheets_update_sheet_properties

Modify sheet properties such as tab color and grid visibility.

sheets_batch_delete_sheets

Delete multiple sheets in one operation.

sheets_batch_format_cells

Format multiple cell ranges in a batch operation.

sheets_format_cells

Apply formatting like colors, fonts, and alignment to cells.

sheets_update_borders

Add or modify borders around cells.

sheets_merge_cells

Merge adjacent cells into a single cell region.

sheets_unmerge_cells

Unmerge previously merged cells.

sheets_add_conditional_formatting

Add rules for conditional formatting.

sheets_create_chart

Create charts in a spreadsheet.

sheets_update_chart

Modify existing charts.

sheets_delete_chart

Remove charts from a spreadsheet.