@mcp-z/mcp-sheets

@mcp-z/mcp-sheets

Docs: https://mcp-z.github.io/mcp-sheets Google Sheets MCP server for reading, writing, and formatting spreadsheets.

Common uses

• Find spreadsheets and sheets
• Append and update data
• Apply formatting, validation, and charts

Transports

MCP supports stdio and HTTP.

Stdio

{
  "mcpServers": {
    "sheets": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-sheets"]
    }
  }
}

HTTP

{
  "mcpServers": {
    "sheets": {
      "type": "http",
      "url": "http://localhost:9004/mcp",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-sheets", "--port=9004"]
      }
    }
  }
}

start is an extension used by npx @mcp-z/cli up to launch HTTP servers for you.

Create a Google Cloud app

• Go to Google Cloud Console.
• Create or select a project.
• Enable the Google Sheets API.
• Create OAuth 2.0 credentials (Desktop app).
• Copy the Client ID and Client Secret.
• Select your MCP transport (stdio for local and http for remote) and platform

• For stdio, choose "APIs & Services", + Create client, "Desktop app" type
• For http, choose "APIs & Services", + Create client, "Web application" type, add your URL (default is http://localhost:3000/oauth/callback based on the --port or PORT)
• For local hosting, add "http://127.0.0.1" for Ephemeral redirect URL

• Enable OAuth2 scopes: openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive
• Add test emails

OAuth modes

Configure via environment variables or the env block in .mcp.json. See server.json for the full list of options.

Loopback OAuth (default)

Environment variables:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Example (stdio) - Create .mcp.json:

{
  "mcpServers": {
    "sheets": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-sheets"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id"
      }
    }
  }
}

Example (http) - Create .mcp.json:

{
  "mcpServers": {
    "sheets": {
      "type": "http",
      "url": "http://localhost:3000",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-sheets", "--port=3000"],
        "env": {
          "GOOGLE_CLIENT_ID": "your-client-id"
        }
      }
    }
  }
}

Local (default): omit REDIRECT_URI → ephemeral loopback. Cloud: set REDIRECT_URI to your public /oauth/callback and expose the service publicly.

Note: start block is a helper in "npx @mcp-z/cli up" for starting an http server from your .mpc.json. See @mcp-z/cli for details.

Service account

Environment variables:

AUTH_MODE=service-account
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

Example:

{
  "mcpServers": {
    "sheets": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-sheets", "--auth=service-account"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json"
      }
    }
  }
}

DCR (self-hosted)

HTTP only. Requires a public base URL.

{
  "mcpServers": {
    "sheets-dcr": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-sheets",
        "--auth=dcr",
        "--port=3456",
        "--base-url=https://oauth.example.com"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

How to use

# List tools
mcp-z inspect --servers sheets --tools

# Find a spreadsheet
mcp-z call sheets spreadsheet-find '{"spreadsheetRef":"Quarterly Report"}'

Tools

• cells-format
• chart-create
• columns-get
• columns-update
• csv-get-columns
• dimensions-batch-update
• dimensions-move
• rows-append
• rows-csv-append
• rows-get
• sheet-copy
• sheet-copy-to
• sheet-create
• sheet-delete
• sheet-find
• sheet-rename
• spreadsheet-copy
• spreadsheet-create
• spreadsheet-find
• spreadsheet-rename
• validation-set
• values-batch-update
• values-clear
• values-csv-update
• values-markdown-update
• values-replace
• values-search

Resources

• spreadsheet

Prompts

• a1-notation

Configuration reference

See server.json for all supported environment variables, CLI arguments, and defaults.