Skip to main content
Glama
Google Sheets MCP Server

Google Sheets MCP Server

Google Sheets MCP Server

A Model Context Protocol (MCP) server providing full Google Sheets functionality. Read, write, format cells, create charts, use formulas, and manage spreadsheets directly from Claude, Cursor, or any MCP-compatible client.

Why I Built This

I created this MCP server for my college assignments, where I frequently work with data in Google Sheets — mostly financial sheets. Tasks like creating charts, writing formulas, formatting tables, and organizing data were repetitive and time-consuming. With this tool, I can automate all of that and focus on what actually matters — logical thinking and analysis — instead of doing the same manual work over and over again. :)

Related MCP server: SCD MCP Docs

Features

Category

Capabilities

Cell Operations

Read, write, batch operations, append rows, clear cells

Formulas

Full support (=SUM(), =VLOOKUP(), =IF(), etc.)

Sheet Management

Create, delete, rename, duplicate sheets

Formatting

Bold, italic, colors, alignment, column widths, merge cells

Charts

Bar, Line, Pie, Column, Area, Scatter charts

Data Operations

Sort, find/replace, get last row

Sharing

Share with users or make public

Quick Start

1. Install

cd /path/to/spreadsheet-mcp
uv sync

2. Google Cloud Setup (Free, One-Time)

  1. Create Project: Go to Google Cloud Console → New Project

  2. Enable APIs:

  3. Create Service Account:

    • Go to APIs & Services → Credentials → Create Credentials → Service Account

    • Download JSON key → Save as credentials/service-account.json

  4. Share Spreadsheets: Share your sheets with the service account email (found in JSON)

3. Run

uv run spreadsheet-mcp

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Claude Code (CLI)

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings → MCP → Add Server):

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Gemini CLI

For Gemini CLI with MCP support, add to your MCP configuration:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Using with npx (Alternative)

If you prefer npx over uv:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": [
        "-y",
        "uv",
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Note: Replace /path/to/spreadsheet-mcp with the actual path where you cloned this repository.

Available Tools (27 Total)

Spreadsheet & Sheet Management

Tool

Description

Example

get_spreadsheet_info

Get metadata and sheet list

"Show me info about spreadsheet abc123"

create_spreadsheet

Create new spreadsheet

"Create a spreadsheet called 'Budget 2024'"

list_sheets

List all sheets/tabs

"What sheets are in this spreadsheet?"

create_sheet

Add a new sheet

"Add a sheet called 'Summary'"

delete_sheet

Remove a sheet

"Delete the sheet with ID 12345"

rename_sheet

Rename a sheet

"Rename sheet 0 to 'Data'"

duplicate_sheet

Copy a sheet

"Duplicate the main sheet"

Cell Operations

Tool

Description

Example

read_cells

Read values from range

"Read cells A1 to D10 from Sheet1"

write_cells

Write values (supports formulas)

"Write headers Name, Age, Score to A1"

batch_read

Read multiple ranges at once

"Read A1:A10 and C1:C10"

batch_write

Write to multiple ranges

"Write data to multiple locations"

append_rows

Add rows at end of data

"Append these new records"

clear_cells

Clear a range

"Clear cells B2:D10"

get_last_row

Find last row with data

"What's the last row in column A?"

Row/Column Operations

Tool

Description

Example

insert_rows

Insert empty rows

"Insert 5 rows at row 10"

insert_columns

Insert empty columns

"Insert 2 columns at column C"

delete_rows

Delete rows

"Delete rows 5-10"

delete_columns

Delete columns

"Delete column B"

Formatting

Tool

Description

Example

format_cells

Apply formatting

"Make header row bold with blue background"

set_column_width

Adjust column width

"Set column A width to 200 pixels"

merge_cells

Merge cell range

"Merge cells A1:C1 for title"

Charts

Tool

Description

Example

create_chart

Create embedded chart

"Create a bar chart from sales data"

list_charts

List all charts

"What charts exist in this spreadsheet?"

delete_chart

Remove a chart

"Delete chart 123456"

Data Operations

Tool

Description

Example

sort_range

Sort data by column

"Sort data by column B ascending"

find_replace

Find and replace text

"Replace 'N/A' with '0' everywhere"

Sharing

Tool

Description

Example

share_spreadsheet

Share or make public

"Make this spreadsheet public"

Usage Examples

Example 1: Create a Sales Report

User: Create a sales report in spreadsheet abc123

Claude will:
1. get_spreadsheet_info("abc123") - Check existing sheets
2. create_sheet("abc123", "Sales Report") - Create new sheet
3. write_cells("abc123", "Sales Report!A1", '[["Product", "Q1", "Q2", "Q3", "Q4", "Total"]]')
4. write_cells("abc123", "Sales Report!A2", '[["Widget", 100, 150, 200, 180, "=SUM(B2:E2)"]]')
5. format_cells(..., bold=True, background_color="#4285F4") - Format header
6. create_chart(..., "COLUMN", "Quarterly Sales") - Add chart

Example 2: Analyze Existing Data

User: Summarize the data in Sheet1

Claude will:
1. read_cells("abc123", "Sheet1!A1:Z1") - Read headers
2. get_last_row("abc123", "Sheet1", "A") - Find data extent
3. read_cells("abc123", "Sheet1!A1:D100") - Read all data
4. Provide summary and insights

Example 3: Format a Table

User: Make the spreadsheet look professional

Claude will:
1. format_cells(..., bold=True, background_color="#1a73e8", font_color="#FFFFFF") - Header
2. set_column_width(..., 150) - Adjust widths
3. format_cells(..., alignment="CENTER") - Center data

A1 Notation Reference

Notation

Description

Sheet1!A1:D10

Cells A1 to D10 in Sheet1

Sheet1!A:A

Entire column A in Sheet1

Sheet1!1:5

Rows 1-5 in Sheet1

A1:B10

Range in first visible sheet

'My Sheet'!A1

Sheet name with spaces (use quotes)

Index Reference

  • Rows: 0-based in formatting (Row 1 = index 0)

  • Columns: 0-based (A=0, B=1, C=2, D=3...)

  • sheet_id: Numeric ID from list_sheets or get_spreadsheet_info

Common Formulas

=SUM(A1:A10)           Sum values
=AVERAGE(B:B)          Average entire column
=COUNT(A:A)            Count numbers
=COUNTA(A:A)           Count non-empty cells
=MAX(A1:A100)          Maximum value
=MIN(A1:A100)          Minimum value
=VLOOKUP(A1,B:C,2,0)   Lookup value
=IF(A1>100,"High","Low") Conditional
=CONCATENATE(A1," ",B1)  Join text
=TODAY()               Current date
=NOW()                 Current date/time

Troubleshooting

Error

Solution

"Service account credentials not found"

Check credentials/service-account.json exists

"403 Forbidden"

Share spreadsheet with service account email

"API not enabled"

Enable Sheets & Drive APIs in Google Cloud Console

"Quota exceeded"

Wait a minute, you're hitting rate limits

File Structure

spreadsheet-mcp/
├── pyproject.toml
├── README.md
├── credentials/
│   └── service-account.json  (your key, gitignored)
└── src/spreadsheet_mcp/
    ├── __init__.py
    ├── auth.py              # Google authentication
    ├── sheets_client.py     # API wrapper (1000+ lines)
    └── server.py            # MCP server (27 tools)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

License

MIT

Available Tools

27 tools
append_rowsA

Append rows to the end of data in a sheet.

Args: spreadsheet_id: The ID of the spreadsheet. range_notation: A1 notation indicating which columns (e.g., "Sheet1!A:D"). values: JSON 2D array of rows to append.

Returns: JSON with updated range and cells appended.

Inputs: values (required), range_notation (required), spreadsheet_id (required). Returns: result

batch_readA

Read values from multiple ranges at once.

Args: spreadsheet_id: The ID of the spreadsheet. ranges: Comma-separated A1 notation ranges (e.g., "Sheet1!A1:B5,Sheet1!D1:E5").

Returns: JSON object mapping each range to its values.

Inputs: ranges (required), spreadsheet_id (required). Returns: result

batch_writeA

Write values to multiple ranges at once.

Args: spreadsheet_id: The ID of the spreadsheet. data: JSON array of objects with 'range' and 'values' keys. Example: '[{"range": "A1:B2", "values": [[1,2],[3,4]]}, {"range": "D1", "values": [["Hello"]]}]'

Returns: JSON with total cells, rows, columns updated.

Inputs: data (required), spreadsheet_id (required). Returns: result

clear_cellsA

Clear all values in a range (keeps formatting).

Args: spreadsheet_id: The ID of the spreadsheet. range_notation: A1 notation range to clear.

Returns: Success message.

Inputs: range_notation (required), spreadsheet_id (required). Returns: result

create_chartA

Create an embedded chart with MULTIPLE SERIES support.

Examples: - Multi-series line chart (auto-detect all columns B-F as series): create_chart("abc", 0, "LINE", "Sheet1!A1:F10", "Stock Prices")

- Explicit series columns (B=1, C=2, D=3, E=4 as separate lines):
  create_chart("abc", 0, "LINE", "A1:E10", "Comparison", 0, 7, 0, "1,2,3,4")
  
- Pie chart (single series from column B):
  create_chart("abc", 0, "PIE", "A1:B5", "Distribution")

Chart Types: - BAR: Horizontal bars (multiple series = grouped bars) - COLUMN: Vertical bars (multiple series = grouped columns) - LINE: Line graph (multiple series = multiple lines, great for trends) - PIE: Circular chart (single series only) - AREA: Stacked area chart - SCATTER: X-Y scatter plot

Multi-Series Example: Data: | Date | ONGC | BPCL | IOCL | NTPC | CIL | Range: "Sheet1!A1:F30" domain_column: 0 (Date column as X-axis) series_columns: "1,2,3,4,5" (or leave empty to auto-detect) Result: 5 lines on one chart, each representing a company

Args: spreadsheet_id: The ID from the spreadsheet URL. sheet_id: Numeric sheet ID where chart will be placed. chart_type: BAR, LINE, PIE, AREA, COLUMN, or SCATTER. data_range: A1 notation of data range (e.g., "Sheet1!A1:F30"). title: Chart title displayed at top. position_row: Row offset for chart placement (0-based). position_col: Column offset for chart placement (0=A, 5=F, 7=H). domain_column: Column index for X-axis labels (0=first column of range). series_columns: Comma-separated indices for series data (e.g., "1,2,3,4,5"). Empty = auto-detect all columns after domain_column.

Returns: JSON with chart_id for later reference.

Inputs: sheet_id (required), chart_type (required), spreadsheet_id (required), title, +5 more. Returns: result

create_sheetA

Create a new sheet/tab in a spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet. title: Name for the new sheet. index: Position for the new sheet (-1 for end).

Returns: JSON with new sheet's ID, title, and index.

Inputs: title (required), spreadsheet_id (required), index. Returns: result

create_spreadsheetA

Create a new Google Spreadsheet.

Args: title: The title for the new spreadsheet. sheet_names: Comma-separated list of sheet names (optional).

Returns: JSON with spreadsheet_id, title, url, and sheets.

Inputs: title (required), sheet_names. Returns: result

delete_chartA

Delete a chart from the spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet. chart_id: The ID of the chart (from list_charts).

Returns: Success message.

Inputs: chart_id (required), spreadsheet_id (required). Returns: result

delete_columnsA

Delete columns from a sheet.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_index: Starting column index (0-based). num_columns: Number of columns to delete.

Returns: Success message.

Inputs: sheet_id (required), num_columns (required), start_index (required), spreadsheet_id (required). Returns: result

delete_rowsA

Delete rows from a sheet.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_index: Starting row index (0-based). num_rows: Number of rows to delete.

Returns: Success message.

Inputs: num_rows (required), sheet_id (required), start_index (required), spreadsheet_id (required). Returns: result

delete_sheetA

Delete a sheet from a spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet (from list_sheets).

Returns: Success message.

Inputs: sheet_id (required), spreadsheet_id (required). Returns: result

duplicate_sheetA

Duplicate/copy a sheet within the same spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet to duplicate. new_title: Name for the duplicated sheet. insert_index: Position for the copy (-1 for end).

Returns: JSON with new sheet's ID, title, and index.

Inputs: sheet_id (required), new_title (required), spreadsheet_id (required), insert_index. Returns: result

find_replaceA

Find and replace text across the spreadsheet or a specific sheet.

Args: spreadsheet_id: The ID of the spreadsheet. find: Text to search for. replace: Text to replace with. sheet_id: Limit to specific sheet (-1 for all sheets). match_case: Case-sensitive matching. match_entire_cell: Only match if cell equals find text exactly.

Returns: JSON with number of occurrences changed.

Inputs: find (required), replace (required), spreadsheet_id (required), sheet_id, +2 more. Returns: result

format_cellsA

Apply formatting to a range of cells.

Examples: - Format header row bold with blue background: format_cells("abc", 0, 0, 1, 0, 5, bold=True, background_color="#4285F4") - Center align cells A1:C10: format_cells("abc", 0, 0, 10, 0, 3, alignment="CENTER")

Note: Indices are 0-based. Row 1 in sheets = index 0. Column A = index 0. end_row and end_col are EXCLUSIVE (like Python ranges).

Args: spreadsheet_id: The ID from the spreadsheet URL. sheet_id: Numeric sheet ID (get from list_sheets or get_spreadsheet_info). start_row: Starting row index (0-based, so row 1 = 0). end_row: Ending row index (exclusive, so rows 1-5 = start=0, end=5). start_col: Starting column index (0-based, A=0, B=1, C=2...). end_col: Ending column index (exclusive). bold: Make text bold (True/False). italic: Make text italic (True/False). font_size: Font size in points (0 to skip, typical: 10-14). font_color: Hex color for text (e.g., "#FF0000"=red, "#FFFFFF"=white). background_color: Hex color for cell background (e.g., "#4285F4"=blue). alignment: "LEFT", "CENTER", or "RIGHT".

Returns: Success message.

Inputs: end_col (required), end_row (required), sheet_id (required), start_col (required), +8 more. Returns: result

get_last_rowA

Find the last row with data in a column.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_name: Name of the sheet. column: Column letter to check (default "A").

Returns: JSON with the last row number (1-based).

Inputs: sheet_name (required), spreadsheet_id (required), column. Returns: result

get_spreadsheet_infoA

Get information about a spreadsheet including all sheets.

Args: spreadsheet_id: The ID of the spreadsheet (from URL).

Returns: JSON with spreadsheet metadata, sheets list, and URL.

Inputs: spreadsheet_id (required). Returns: result

insert_columnsA

Insert empty columns at a specific position.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_index: Column index to insert at (0-based, so column A = index 0). num_columns: Number of columns to insert.

Returns: Success message.

Inputs: sheet_id (required), num_columns (required), start_index (required), spreadsheet_id (required). Returns: result

insert_rowsA

Insert empty rows at a specific position.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_index: Row index to insert at (0-based, so row 1 = index 0). num_rows: Number of rows to insert.

Returns: Success message.

Inputs: num_rows (required), sheet_id (required), start_index (required), spreadsheet_id (required). Returns: result

list_chartsA

List all charts in a spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet.

Returns: JSON list of charts with IDs, titles, and positions.

Inputs: spreadsheet_id (required). Returns: result

list_sheetsA

List all sheets/tabs in a spreadsheet.

Args: spreadsheet_id: The ID of the spreadsheet.

Returns: JSON list of sheets with their IDs, titles, and dimensions.

Inputs: spreadsheet_id (required). Returns: result

merge_cellsA

Merge cells in a range.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_row: Starting row index (0-based). end_row: Ending row index (exclusive). start_col: Starting column index (0-based). end_col: Ending column index (exclusive). merge_type: "MERGE_ALL", "MERGE_COLUMNS", or "MERGE_ROWS".

Returns: Success message.

Inputs: end_col (required), end_row (required), sheet_id (required), start_col (required), +3 more. Returns: result

read_cellsA

Read cell values from a spreadsheet range.

Examples: - read_cells("abc123", "Sheet1!A1:D10") → Read 10 rows, 4 columns - read_cells("abc123", "Sheet1!A:A") → Read entire column A - read_cells("abc123", "A1:B5") → Read from first visible sheet

Args: spreadsheet_id: The ID from the spreadsheet URL. range_notation: A1 notation range. Use 'SheetName!A1:B5' format.

Returns: JSON 2D array of cell values. Empty cells may be omitted.

Inputs: range_notation (required), spreadsheet_id (required). Returns: result

rename_sheetA

Rename a sheet.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. new_title: New name for the sheet.

Returns: Success message.

Inputs: sheet_id (required), new_title (required), spreadsheet_id (required). Returns: result

set_column_widthB

Set the width of columns.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_col: Starting column index (0-based, A=0). end_col: Ending column index (exclusive). width: Width in pixels.

Returns: Success message.

Inputs: width (required), end_col (required), sheet_id (required), start_col (required), +1 more. Returns: result

share_spreadsheetA

Share a spreadsheet with someone or make it publicly accessible.

Args: spreadsheet_id: The ID of the spreadsheet. email: Email address to share with (optional if make_public=True). role: Permission level - "reader", "writer", or "commenter". make_public: If True, makes spreadsheet accessible to anyone with link.

Returns: JSON with sharing result.

Inputs: spreadsheet_id (required), role, email, make_public. Returns: result

sort_rangeA

Sort data in a range by a column.

Args: spreadsheet_id: The ID of the spreadsheet. sheet_id: The numeric ID of the sheet. start_row: Starting row index (0-based). end_row: Ending row index (exclusive). start_col: Starting column index (0-based). end_col: Ending column index (exclusive). sort_column: Column index to sort by (0-based, relative to range). ascending: True for A-Z/0-9, False for Z-A/9-0.

Returns: Success message.

Inputs: end_col (required), end_row (required), sheet_id (required), start_col (required), +4 more. Returns: result

write_cellsA

Write values to cells. Supports formulas (start with =).

Examples: - write_cells("abc123", "Sheet1!A1", '[["Name", "Age"], ["Alice", 30]]') - write_cells("abc123", "Sheet1!E1", '[["=SUM(A1:D1)"], ["=SUM(A2:D2)"]]') - write_cells("abc123", "A1", '[["Header1", "Header2", "Header3"]]')

Args: spreadsheet_id: The ID from the spreadsheet URL. range_notation: Starting cell in A1 notation (e.g., "Sheet1!A1"). values: JSON 2D array. Each inner array is a row. Formulas: use "=SUM(A1:A10)", "=AVERAGE(B:B)", etc.

Returns: JSON with updated_cells count and updated_range.

Inputs: values (required), range_notation (required), spreadsheet_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 27 tools

    Disambiguation5/5

    Every tool targets a distinct operation: sheet management, cell reads/writes, row/column modifications, formatting, charts, sorting, find/replace, and sharing. Even similar tools like read_cells vs batch_read and write_cells vs batch_write are clearly separated by single vs. multi-range scope, and descriptions clarify the boundaries.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., create_sheet, delete_sheet, read_cells, format_cells, list_charts). No camelCase or mismatched conventions are present, and verbs are consistently placed first.

    Tool Count2/5

    With 27 tools, the set exceeds the 25-tool threshold for 'heavy' servers. While each tool has a clear purpose, the count feels excessive for typical spreadsheet interactions; some batch and formatting operations could be consolidated without losing functionality.

    Completeness3/5

    Core spreadsheet and sheet lifecycle operations are well covered (create, read, list, rename, duplicate, delete sheets; read/write cells; row/column manipulation; charts; sharing). However, there is no tool to delete a spreadsheet or rename the spreadsheet itself, which are notable gaps in full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers