Google Sheets

This Google Sheets MCP server lets AI agents interact with spreadsheets directly, enabling you to read, write, and manage sheets and workbooks through a simple MCP interface.

How to use

You connect an MCP client to this server to perform common Google Sheets operations. Use a standard HTTP MCP endpoint for remote integration or run the server locally to operate through the command line. Typical workflows include listing sheets, reading data, editing cells, inserting rows or columns, and renaming sheets or documents. You can re-authenticate when credentials expire to ensure uninterrupted access.

To start quickly, run the local server and use the provided actions to manipulate spreadsheets. If you prefer an hosted endpoint for browser-based or tool-integrated flows, deploy with the SSE transport and point your client to the hosted URL.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Clone the project, install dependencies, and build the server.

git clone https://github.com/mkummer225/google-sheets-mcp
cd google-sheets-mcp
npm install
npm run build

Run locally

Start the MCP server locally. You will be prompted to authenticate with your Google account when necessary.

Then run the start command to begin serving MCP requests.

npm run start

Hosted / Railway (SSE transport)

If you need a URL-based MCP endpoint for client integrations, deploy with SSE transport to a hosting provider like Railway. This setup enables a remote MCP URL that forwards messages to the local server via SSE.

Steps to deploy and run in hosting mode:

# Build for hosting
npm run build

# Required environment variables (set these in your hosting environment)
MCP_TRANSPORT=sse
PORT=3000
GSHEETS_OAUTH_JSON=YOUR_OAUTH_JSON_OR_BASE64
GSHEETS_CREDENTIALS_JSON=YOUR_PREAUTHORIZED_CREDENTIALS_JSON

# Deploy dist/ to your host and start the server
# Example (host-specific):
node dist/index.js

MCP configuration example

Use the following configuration to run both a remote HTTP endpoint and a local stdio server. The HTTP entry provides a hosted URL for clients, while the stdio entry runs locally via npm.

{
  "mcpServers": [
    {
      "type": "http",
      "name": "google_sheets_mcp",
      "url": "https://<your-railway-app>.up.railway.app/sse",
      "args": []
    },
    {
      "type": "stdio",
      "name": "google_sheets_mcp",
      "command": "npm",
      "args": ["run","start"],
      "env": [
        {"name": "MCP_TRANSPORT", "value": "sse"},
        {"name": "PORT", "value": "3000"},
        {"name": "GSHEETS_OAUTH_JSON", "value": "YOUR_OAUTH_JSON"},
        {"name": "GSHEETS_CREDENTIALS_JSON", "value": "YOUR_CREDENTIALS_JSON"}
      ]
    }
  ]
}

Notes on security and credentials

Keep OAuth credentials and any downloaded keys out of version control. Use a secrets manager or environment variables in your hosting environment to supply GSHEETS_OAUTH_JSON and GSHEETS_CREDENTIALS_JSON securely.

Troubleshooting

If you encounter authentication prompts, ensure your Google Cloud project has the Google Sheets API enabled and that OAuth credentials are correctly configured. Re-authenticate as needed using the provided action refresh_auth.

Examples of available actions

The server exposes a set of actions you can perform through MCP clients: refresh_auth, list_sheets, create_sheet, create_spreadsheet, read_all_from_sheet, read_headings, read_rows, read_columns, edit_cell, edit_row, edit_column, insert_row, insert_column, rename_sheet, and rename_doc.

Available tools

refresh_auth

Re-authenticate your Google Account when credentials expire

list_sheets

List all sheets/tabs in a Google Spreadsheet

create_sheet

Create a new sheet/tab in a Google Spreadsheet

create_spreadsheet

Create a new Google Spreadsheet

read_all_from_sheet

Read all data from a specified sheet

read_headings

Read the column headings from a sheet

read_rows

Read specific rows from a sheet

read_columns

Read specific columns from a sheet

edit_cell

Edit a single cell in a sheet

edit_row

Edit an entire row in a sheet

edit_column

Edit an entire column in a sheet

insert_row

Insert a new row at a specified position

insert_column

Insert a new column at a specified position

rename_sheet

Rename a sheet/tab in a spreadsheet

rename_doc

Rename a Google Spreadsheet