Uses Google Cloud service accounts for secure authentication and API access to Google Sheets
Integrates with Google Drive API for authentication and access to Google Sheets documents
Allows retrieving spreadsheet summaries and specific sheet data from Google Sheets, with support for navigating large spreadsheets through a two-tool approach
Claude Desktop Extension: Google Sheets MCP Server
A Claude Desktop Extension (DXT) that provides seamless access to Google Sheets through the Model Context Protocol (MCP). This extension allows Claude to efficiently navigate and analyze Google Sheets data using a two-tool approach designed for handling large spreadsheets with secure service account authentication.
Features
Get Spreadsheet Summary: Retrieve metadata about a Google Sheet including name, sheet count, and sheet names - perfect for navigation and understanding structure
Get Specific Sheet Data: Retrieve complete data from a specific worksheet within a spreadsheet - optimized for targeted analysis
Structured Data Access: Returns spreadsheet data as JSON including all worksheets, cell values, formatting, and metadata
Automatic URL Parsing: Extracts sheet IDs from various Google Sheets URL formats
Secure Authentication: Service account-based authentication with Google APIs
Real-time Access: Direct integration with Google Sheets API
Desktop Extension: Single-click installation in Claude Desktop
AI-Friendly Format: Data returned in structured JSON format Claude can analyze, process, and work with directly
Large Spreadsheet Optimization: Two-tool approach allows efficient handling of spreadsheets with many sheets by getting overview first
Prerequisites
Node.js 18+ installed
Google Cloud Project with Google Sheets API enabled
Google Service Account credentials configured
Claude Desktop application
Installation
Clone the repository:
git clone https://github.com/stephenyu/mcp-googlesheet cd mcp-googlesheetInstall dependencies:
npm installConfigure Google Service Account:
Create a Google Cloud Project
Enable Google Sheets API and Google Drive API
Create a Service Account
Download the service account JSON file
Configure extension settings (see Configuration section)
Install the extension in Claude Desktop:
Build the extension:
npm run pack
(usesdxt pack
under the hood)Open Claude Desktop
Go to Settings → Extensions
Click "Install Extension"
Select the generated
mcp-googlesheet.dxt
file
Configuration
Extension Settings
The extension requires a Google Service Account JSON credentials file. In Claude Desktop extension settings, configure:
Credentials JSON File Path: Path to your Google Service Account JSON file (e.g.,
/path/to/service-account-key.json
)
This file must contain all necessary authentication information including client_email
, private_key
, and project_id
.
Testing Your Credentials
Before using the extension, you can test your credentials JSON file:
This will verify that:
The file can be read and parsed
All required fields are present
The private key format is correct (includes BEGIN/END markers)
The credentials are valid
Credentials JSON File Format
Your Google Service Account JSON file should look like this:
The extension will automatically extract the required fields (client_email
, private_key
, and project_id
) from this file.
Google Cloud Setup
Go to Google Cloud Console
Create a new project or select existing one
Enable Google Sheets API and Google Drive API
Create a Service Account:
Go to "APIs & Services" → "Credentials"
Click "Create Credentials" → "Service Account"
Download the JSON key file
Share your Google Sheets with the service account email
For detailed setup instructions, see SETUP.md.
Usage
Available Tools
The extension provides two complementary tools designed for efficient navigation of large spreadsheets:
get_spreadsheet_summary
: Get an overview of a Google SheetParameters: url (Complete Google Sheets URL)
Returns: Spreadsheet metadata including title, sheet count, sheet names, creation/modification dates
Use case: Understanding spreadsheet structure and choosing which sheet to analyze
get_spreadsheet_sheet_data
: Get complete data from a specific sheetParameters: url (Complete Google Sheets URL), sheet_name (Name of the specific sheet)
Returns: Complete cell data, formatting, and metadata for the specified sheet
Use case: Detailed analysis of specific worksheet data
Example Usage in Claude Desktop
Workflow for Large Spreadsheets
The two-tool approach is optimized for large spreadsheets:
Start with Summary: Use
get_spreadsheet_summary
to see what sheets are availableChoose Target Sheet: Based on the summary, identify which sheet contains the data you need
Get Specific Data: Use
get_spreadsheet_sheet_data
to retrieve complete data from the target sheet
This approach avoids downloading massive amounts of data when you only need specific worksheets.
Supported URL Formats
The extension can extract sheet IDs from various Google Sheets URL formats:
Standard format:
https://docs.google.com/spreadsheets/d/SHEET_ID/edit
With view parameters:
https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0
With additional parameters:
https://docs.google.com/spreadsheets/d/SHEET_ID/edit?usp=sharing
Development
Project Structure
Running in Development
Start the development server:
npm run devTest the extension:
npm testTest credentials:
npm run test:credentials /path/to/your/service-account-key.jsonBuild the extension:
npm run packInstall in Claude Desktop:
Open the generated
mcp-googlesheet.dxt
file with Claude Desktop
Security
Service account authentication ensures secure access to user data
No data is stored locally beyond temporary session tokens
All API calls use HTTPS
Service account only has read-only access to spreadsheets
Only the JSON file path is stored in extension settings; credentials remain in your local file system
Debugging Environment Variables
To debug environment variable issues, run the environment test script:
This will help identify:
Whether environment variables are set correctly
If placeholders are being resolved properly
File access permissions
JSON file validity
Google API authentication status
Google Cloud project configuration
Debug Mode
Enable debug logging by setting:
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request
License
GNU General Public License v3.0 or later - see LICENSE file for details
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Support
For issues and questions:
Check the troubleshooting section
Review the architecture documentation
Open an issue on GitHub
Changelog
v1.0.0
Initial release with structured JSON data access
Two-tool approach for efficient large spreadsheet handling
Support for retrieving spreadsheet summaries and specific sheet data
Automatic URL parsing for sheet ID extraction
Service account authentication
MCP server implementation with comprehensive error handling
This server cannot be installed
A Claude Desktop Extension that provides seamless access to Google Sheets data through the Model Context Protocol, allowing Claude to efficiently navigate and analyze spreadsheets using a two-tool approach for handling large datasets.
Related MCP Servers
- -securityFlicense-qualityAllows interaction with Google Calendar through Claude Desktop using the Model Context Protocol, enabling calendar event management and schedule analysis.Last updated -2
- AsecurityAlicenseAqualityA utility tool that enables Claude Desktop to interact with external tools via the Model Context Protocol, providing features like email sending and simple calculations while simplifying the MCP setup process.Last updated -2013MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude to load CSV files and execute JavaScript data analysis scripts for advanced data exploration and insights generation.Last updated -28MIT License
- -securityFlicense-qualityConnects Claude to Google Docs, allowing users to list, read, create, update, search, and delete documents in their Google Drive through natural language interactions.Last updated -1