mcp-google-sheets

mcp-google-sheets is a Python-based MCP server that acts as a bridge between MCP-compatible clients (such as Claude Desktop) and the Google Sheets API. It exposes a suite of tools that let you read, write, list, and manage spreadsheets and their sheets, enabling AI-driven automation and data manipulation within Google Sheets. To use it, run the server via uvx as shown in the quick start, providing authentication credentials through environment variables. Once the server is running, connect your MCP client to the server endpoint and begin issuing tool commands described in the tool list (for example: get_sheet_data, update_cells, list_spreadsheets, list_sheets). You can also enable tool filtering to limit which tools are active in a given session, which helps reduce the AI context size during conversations. When connected, you’ll interact with the tools by passing the appropriate parameters (strings, sometimes optional) defined for each tool.

The server supports multiple authentication methods (recommended service accounts, OAuth, or direct credential injection via environment variables). Typical usage involves setting SERVICE_ACCOUNT_PATH to point to a Google service account key file and optionally DRIVE_FOLDER_ID to constrain operations to a specific Drive folder. After starting the server with uvx mcp-google-sheets@latest, your MCP client can send natural-language prompts that map to the available tools to perform operations like reading sheet data, updating cells, or listing spreadsheets.

Prerequisites:

• Python environment (recommended 3.8+)
• uv/uvx tooling (for one-line run capability)
• Access to Google Cloud APIs with a credentials file (service account recommended)

Installation steps:

1. Install uv (if you don’t have it):
   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows (PowerShell): iwr https://astral.sh/uv/install.ps1 | iex
   • Or install via pip: pip install uv
2. Ensure Python dependencies are installed for the MCP server (usually via the project’s setup):
   • git clone https://github.com/xing5/mcp-google-sheets.git
   • cd mcp-google-sheets
   • python -m pip install -r requirements.txt
3. Prepare Google Cloud credentials:
   • Create a service account key JSON and save it to a secure path, e.g. /path/to/credentials.json
   • If needed, enable Google Sheets and Drive APIs for the project
4. Run the server with uvx:
   • uvx mcp-google-sheets@latest
   • This will download the latest code and start the server (one-line run)

Optional:

• Set environment variables for authentication and scope, e.g. SERVICE_ACCOUNT_PATH and DRIVE_FOLDER_ID, before starting the server in your shell or within a container.

Tips and common considerations:

• Tool filtering: By default, all 19 tools are available. Use --include-tools or ENABLED_TOOLS to enable only a subset and reduce the context window used by your AI agent.
• Environment variables: SERVICE_ACCOUNT_PATH is the primary method for Google authentication. You can also explore OAuth setups or direct credential injection if needed for your workflow.
• When using uvx, always prefer the @latest tag to ensure you have the newest features and bug fixes.
• If connecting from a client like Claude Desktop, ensure the client is configured to connect to the running MCP server and that the server is accessible from the client network.
• If you encounter permission errors, verify that the service account has access to the target Google Drive folder and the appropriate Sheets/Drive APIs are enabled in the Google Cloud Console.