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. :)

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)

Create Project: Go to Google Cloud Console → New Project
Enable APIs:

Create Service Account:

Go to APIs & Services → Credentials → Create Credentials → Service Account
Download JSON key → Save as credentials/service-account.json

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

@dudegladiator

License

MIT

Google Sheets MCP Server