Google Sheets MCP Server
Provides full Google Sheets functionality including reading, writing, formatting cells, creating charts, using formulas, managing sheets, sharing, and data operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Sheets MCP Server Create a new spreadsheet called 'Monthly Budget' with columns for income and expenses"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ( |
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 sync2. 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-mcpMCP Client Configuration
Claude Desktop
Add to your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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 metadata and sheet list | "Show me info about spreadsheet abc123" |
| Create new spreadsheet | "Create a spreadsheet called 'Budget 2024'" |
| List all sheets/tabs | "What sheets are in this spreadsheet?" |
| Add a new sheet | "Add a sheet called 'Summary'" |
| Remove a sheet | "Delete the sheet with ID 12345" |
| Rename a sheet | "Rename sheet 0 to 'Data'" |
| Copy a sheet | "Duplicate the main sheet" |
Cell Operations
Tool | Description | Example |
| Read values from range | "Read cells A1 to D10 from Sheet1" |
| Write values (supports formulas) | "Write headers Name, Age, Score to A1" |
| Read multiple ranges at once | "Read A1:A10 and C1:C10" |
| Write to multiple ranges | "Write data to multiple locations" |
| Add rows at end of data | "Append these new records" |
| Clear a range | "Clear cells B2:D10" |
| Find last row with data | "What's the last row in column A?" |
Row/Column Operations
Tool | Description | Example |
| Insert empty rows | "Insert 5 rows at row 10" |
| Insert empty columns | "Insert 2 columns at column C" |
| Delete rows | "Delete rows 5-10" |
| Delete columns | "Delete column B" |
Formatting
Tool | Description | Example |
| Apply formatting | "Make header row bold with blue background" |
| Adjust column width | "Set column A width to 200 pixels" |
| Merge cell range | "Merge cells A1:C1 for title" |
Charts
Tool | Description | Example |
| Create embedded chart | "Create a bar chart from sales data" |
| List all charts | "What charts exist in this spreadsheet?" |
| Remove a chart | "Delete chart 123456" |
Data Operations
Tool | Description | Example |
| Sort data by column | "Sort data by column B ascending" |
| Find and replace text | "Replace 'N/A' with '0' everywhere" |
Sharing
Tool | Description | Example |
| 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 chartExample 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 insightsExample 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 dataA1 Notation Reference
Notation | Description |
| Cells A1 to D10 in Sheet1 |
| Entire column A in Sheet1 |
| Rows 1-5 in Sheet1 |
| Range in first visible sheet |
| 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_sheetsorget_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/timeTroubleshooting
Error | Solution |
"Service account credentials not found" | Check |
"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 toolsappend_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
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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
Connect AI assistants to Google Sheets through controlled tools for reading and updating rows.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
Google Sheets via Apify: write Apify datasets or JSON rows to a sheet, or read a sheet as JSON.
The Excel engine for AI agents: read, check and edit Excel models over MCP.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to interact with Google Sheets for reading, writing, and managing spreadsheets through a set of MCP tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients like Claude Desktop and Cursor to interact with Google Docs, Sheets, and Drive, providing tools for reading, writing, formatting documents, managing spreadsheets, and searching Drive files.MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to read, write, append, create, and clear Google Sheets data using natural language.-
- AlicenseNot gradedqualityCmaintenanceEnables reading, writing, and managing Google Sheets from Claude and any MCP-compatible AI client through tools like append_row, update_range, and batch updates.28 npm1MIT