Skip to main content
Glama

Google Sheets Analytics MCP

TNTM Google Sheets Analytics MCP Server

TNTM Logo

A clean, practical MCP (Model Context Protocol) server for analyzing Google Sheets data with multi-tab support. Built for Claude Desktop and other MCP-compatible AI assistants by TNTM.

🚀 Features

  • Smart Sync - Sync Google Sheets with configurable row limits to prevent timeouts
  • Multi-tab Support - Query across multiple sheets with SQL JOINs
  • SQL Queries - Direct SQL access to synced data
  • Sheet Analysis - Get suggestions for cross-sheet queries
  • Quick Preview - Preview sheets without full sync
  • Performance Optimized - Row limits and result pagination for large datasets

📋 Prerequisites

  • Python 3.8+
  • Claude Desktop or another MCP-compatible client
  • Google Cloud Project with Sheets API enabled
  • OAuth2 credentials from Google Cloud Console

🛠️ Setup

1. Clone and Install

git clone https://github.com/yourusername/google-sheet-analytics-mcp.git cd google-sheet-analytics-mcp python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt

2. Google Cloud Setup

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable the Google Sheets API
  4. Create OAuth2 credentials (Desktop Application)
  5. Download the credentials and save as credentials.json in the project root

3. Run Automated Setup

python3 setup.py

This will:

  • Set up OAuth authentication
  • Configure Claude Desktop automatically
  • Test the connection

Or configure MCP client manually:

{ "mcpServers": { "google-sheets-analytics": { "command": "/path/to/your/venv/bin/python", "args": ["/path/to/google-sheet-analytics-mcp/src/mcp_server.py"] } } }

4. First Run

Restart your MCP client (e.g., Claude Desktop) and the OAuth flow will start automatically on first tool use.

🔧 Tools

smart_sync

Sync Google Sheet data with performance controls.

Use smart_sync with url "https://docs.google.com/spreadsheets/d/your_sheet_id" and max_rows 500
  • url (required): Google Sheets URL
  • max_rows (optional): Max rows per sheet (default: 1000)
  • sheets (optional): Array of specific sheet names to sync

query_sheets

Run SQL queries on synced data, including JOINs across tabs.

Use query_sheets with query "SELECT * FROM sheet1 JOIN sheet2 ON sheet1.id = sheet2.id LIMIT 10"
  • query (required): SQL query to execute

list_synced_sheets

View all synced sheets and their table names.

Use list_synced_sheets

analyze_sheets

Get suggestions for queries across multiple sheets.

Use analyze_sheets with question "How can I combine sales data with customer data?"
  • question (required): What you want to analyze

get_sheet_preview

Quick preview without syncing.

Use get_sheet_preview with url "https://docs.google.com/spreadsheets/d/your_sheet_id" and rows 20
  • url (required): Google Sheets URL
  • sheet_name (optional): Specific sheet to preview
  • rows (optional): Number of rows to preview (default: 10)

📊 How It Works

  1. Authentication - Uses OAuth2 to securely access Google Sheets API
  2. Sync - Downloads sheet data to local SQLite database with configurable limits
  3. Query - Enables SQL queries across all synced sheets
  4. Multi-tab - Each sheet becomes a separate table, joinable via SQL

🏗️ Project Structure

google-sheet-analytics-mcp/ ├── src/ │ ├── mcp_server.py # Main MCP server implementation │ └── auth/ │ └── oauth_setup.py # Unified OAuth authentication module ├── setup.py # Unified setup script (handles everything) ├── requirements.txt # Python dependencies ├── credentials.json.example # Example OAuth credentials format ├── README.md # This file ├── LICENSE # MIT License ├── CLAUDE.md # Claude-specific instructions ├── data/ # Runtime data (created automatically) │ ├── token.json # OAuth token (created during setup) │ └── sheets_data.sqlite # Local database (created on first sync) └── venv/ # Virtual environment (created during setup)

⚡ Performance

  • Row Limits: Default 1000 rows per sheet (configurable)
  • Result Limits: Query results limited to 100 rows
  • Local Storage: SQLite database for fast repeated queries
  • Metadata Tracking: Efficient re-syncing of changed data
  • Memory Efficient: Streaming data processing

🔍 Example Use Cases

Multi-tab Analysis

-- Combine sales data with customer information SELECT s.product_name, s.sales_amount, c.customer_name, c.customer_segment FROM sales_data s JOIN customer_data c ON s.customer_id = c.id WHERE s.sales_amount > 1000

Cross-sheet Aggregation

-- Total revenue by region from multiple sheets SELECT region, SUM(amount) as total_revenue FROM ( SELECT region, amount FROM q1_sales UNION ALL SELECT region, amount FROM q2_sales ) GROUP BY region ORDER BY total_revenue DESC

🔒 Security

  • OAuth2 authentication with Google
  • Credentials stored locally (never committed to repo)
  • Read-only access to Google Sheets
  • Local SQLite database (no external data transmission)

🐛 Troubleshooting

Common Issues

IssueSolution
"No credentials found"Ensure credentials.json exists in project root or config/ directory
"Authentication failed"Check token status with venv/bin/python src/auth/oauth_setup.py --status
"Token expired"Run venv/bin/python src/auth/oauth_setup.py --test (auto-refreshes)
"Sync timeout"Reduce max_rows parameter in smart_sync
"Tools not appearing"Restart Claude Desktop after configuration
"Rate limit errors"Wait a few minutes and try again with smaller batches

OAuth Troubleshooting

  • Check status: venv/bin/python src/auth/oauth_setup.py --status
  • Test auth: venv/bin/python src/auth/oauth_setup.py --test
  • Reset OAuth: venv/bin/python src/auth/oauth_setup.py --reset
  • Manual setup: venv/bin/python src/auth/oauth_setup.py --manual

MCP Server Not Appearing

  1. Ensure Claude Desktop is fully closed
  2. Verify config: cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
  3. Check the config includes the google-sheets-analytics server
  4. Restart Claude Desktop
  5. Check developer console for errors

Database Issues

  • Database location: data/sheets_data.sqlite
  • Reset database: Delete the file and re-sync
  • Check synced sheets: Use the list_synced_sheets tool

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments


Need help? Open an issue on GitHub or check the troubleshooting section above.

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

This MCP server enables AI assistants to automatically sync Google Sheets data to a local database and perform natural language queries and analysis on spreadsheet data.

  1. 🚀 Features
    1. 📋 Prerequisites
      1. 🛠️ Setup
        1. 1. Clone and Install
        2. 2. Google Cloud Setup
        3. 3. Run Automated Setup
        4. 4. First Run
      2. 🔧 Tools
        1. smart_sync
        2. query_sheets
        3. list_synced_sheets
        4. analyze_sheets
        5. get_sheet_preview
      3. 📊 How It Works
        1. 🏗️ Project Structure
          1. ⚡ Performance
            1. 🔍 Example Use Cases
              1. Multi-tab Analysis
              2. Cross-sheet Aggregation
            2. 🔒 Security
              1. 🐛 Troubleshooting
                1. Common Issues
                2. OAuth Troubleshooting
                3. MCP Server Not Appearing
                4. Database Issues
              2. 🤝 Contributing
                1. 📄 License
                  1. 🙏 Acknowledgments

                    Related MCP Servers

                    • -
                      security
                      A
                      license
                      -
                      quality
                      This MCP server integrates with Google Drive to allow listing, reading, and searching files, as well as the ability to read and write to Google Sheets.
                      Last updated -
                      866
                      2
                      JavaScript
                      MIT License
                    • -
                      security
                      A
                      license
                      -
                      quality
                      An MCP server that enables AI assistants to access and interact with Google Classroom data, allowing users to view courses, course details, and assignments through natural language commands.
                      Last updated -
                      646
                      1
                      JavaScript
                      MIT License
                    • -
                      security
                      F
                      license
                      -
                      quality
                      This MCP Server provides a natural language interface to interact with Google's Policy Analyzer API, allowing users to analyze policies and evaluate compliance through conversations.
                      Last updated -
                      Python
                      • Linux
                      • Apple
                    • -
                      security
                      F
                      license
                      -
                      quality
                      An MCP server that enables interaction with Google Sheets through natural language, allowing users to create, read, update, and manage spreadsheet data via the Google Sheets API v4.
                      Last updated -
                      Python

                    View all related MCP servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/talknerdytome-labs/google-sheet-analytics-mcp'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server