Skip to main content
Glama

Google Analytics MCP Server

by gomarble-ai
GitHub
Python
MIT License
12
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Google Analytics MCP Server 📊

License: MIT Python 3.10+ FastMCP

A FastMCP-powered Model Context Protocol server for Google Analytics 4 API integration with automatic OAuth 2.0 authentication

Connect Google Analytics 4 data directly to Claude Desktop and other MCP clients with seamless OAuth 2.0 authentication, automatic token refresh, comprehensive reporting, and analytics capabilities.

🌟 Open Source & Community

GoMarble AI Open Source Projects

Check out our other open source contributions at GoMarble AI GitHub:

  • Analytics Tools - Advanced analytics and reporting solutions

  • AI Integration - Tools for integrating AI with marketing platforms

  • MCP Servers - Additional Model Context Protocol implementations

  • Marketing Automation - Open source marketing automation tools

Join Our Community

Connect with other developers and marketers using AI in advertising:

Join our Slack Community - AI in Ads

  • 💬 Discuss AI applications in advertising

  • 🤝 Share your projects and get feedback

  • 📚 Learn from industry experts

  • 🚀 Collaborate on open source projects

  • 🔧 Get help with technical implementation

🚀 Try Our One-Click Integration

Skip the manual setup and get started instantly:

One-Click MCP Integration - Connect Google Analytics and other tools to Claude Desktop in seconds

  • ⚡ Instant Setup - No manual configuration required

  • 🔐 Secure Authentication - Built-in OAuth handling

  • 📊 Multiple Integrations - Google Analytics, Google Ads, Meta Ads, and more

  • 📖 Documentation - Complete integration guide at gomarble.ai/docs

✨ Features

  • 🔐 Automatic OAuth 2.0 - One-time browser authentication with auto-refresh

  • 🔄 Smart Token Management - Handles expired tokens automatically

  • 📊 Comprehensive Reporting - Access all GA4 metrics and dimensions

  • 🏢 Property Management - List and manage Google Analytics properties

  • 📈 Advanced Analytics - Page views, users, events, traffic sources, and more

  • 🚀 FastMCP Framework - Built on the modern MCP standard

  • 🖥️ Claude Desktop Ready - Direct integration with Claude Desktop

  • 🛡️ Secure Local Storage - Tokens stored locally, never exposed

📋 Available Tools

Tool

Description

Parameters

Example Usage

list_properties

List all GA4 accounts and properties

account_id

(optional)

"List all my Google Analytics properties"

get_page_views

Get page view metrics

property_id

,

start_date

,

end_date

,

dimensions

(optional)

"Show me page views for last month"

get_active_users

Get active users metrics

property_id

,

start_date

,

end_date

,

dimensions

(optional)

"Get active users by day for last week"

get_events

Get event metrics

property_id

,

start_date

,

end_date

,

dimensions

(optional)

"Show me events data for property 123456789"

get_traffic_sources

Get traffic source data

property_id

,

start_date

,

end_date

,

dimensions

(optional)

"Analyze traffic sources for last 30 days"

get_device_metrics

Get device-based metrics

property_id

,

start_date

,

end_date

,

dimensions

(optional)

"Show device breakdown for last month"

run_report

Comprehensive custom reporting

property_id

,

start_date

,

end_date

,

metrics

,

dimensions

, filters, etc.

"Create custom report with sessions and conversions by country"

Note: All tools automatically handle authentication - no token parameters required!

🚀 Quick Start

Prerequisites

Before setting up the MCP server, you'll need:

  • Python 3.10+ installed

  • A Google Cloud Platform account

  • A Google Analytics 4 property with data access

🔧 Step 1: Google Cloud Platform Setup

1.1 Create Google Cloud Project

  1. Go to

  2. Create a new project:

    • Click "Select a project" → "New Project"

    • Enter project name (e.g., "Google Analytics MCP")

    • Click "Create"

1.2 Enable Google Analytics APIs

  1. In your Google Cloud Console:

    • Go to "APIs & Services" → "Library"

    • Search for "Google Analytics Data API" and enable it

1.3 Create OAuth 2.0 Credentials

  1. Go to "APIs & Services" → "Credentials"

  2. Click "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"

  3. Configure consent screen (if first time):

    • Click "Configure Consent Screen"

    • Choose "External" (unless you have Google Workspace)

    • Fill required fields:

      • App name: "Google Analytics MCP"

      • User support email: Your email

      • Developer contact: Your email

    • Add scopes:

      • https://www.googleapis.com/auth/analytics

      • https://www.googleapis.com/auth/analytics.readonly

    • Click "Save and Continue" through all steps

  4. Create OAuth Client:

    • Application type: "Desktop application"

    • Name: "Google Analytics MCP Client"

    • Click "Create"

  5. Download credentials:

    • Click "Download JSON" button

    • Save file as client_secret_[long-string].json in your project directory

🔧 Step 2: Google Analytics Access

2.1 Ensure Analytics Access

  1. Sign in to

  2. Verify you have access to GA4 properties

  3. Note your property IDs (found in GA4 Admin → Property Settings)

  4. Ensure your Google account has at least Viewer access to the properties you want to query

🔧 Step 3: Installation & Setup

3.1 Clone and Install

# Clone the repository git clone https://github.com/yourusername/google-analytics-mcp-server.git cd google-analytics-mcp-server # Create virtual environment (recommended) python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt

3.2 Environment Configuration

Create a .env file in your project directory:

# Copy the example file cp .env.example .env

Edit .env with your credentials:

# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud) GOOGLE_ANALYTICS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Example

GOOGLE_ANALYTICS_OAUTH_CONFIG_PATH=/Users/john/google-analytics-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ Step 4: Claude Desktop Integration

4.1 Locate Claude Configuration

Find your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 Add MCP Server Configuration

Edit the configuration file and add your Google Analytics MCP server:

{ "mcpServers": { "google-analytics": { "command": "/full/path/to/your/project/.venv/bin/python", "args": [ "/full/path/to/your/project/server.py" ] } } }

Real Example:

{ "mcpServers": { "google-analytics": { "command": "/Users/marble-dev-01/workspace/google_analytics_mcp/.venv/bin/python", "args": [ "/Users/marble-dev-01/workspace/google_analytics_mcp/server.py" ] } } }

Important:

  • Use absolute paths for all file locations

  • On Windows, use forward slashes / or double backslashes \\ in paths

4.3 Restart Claude Desktop

Close and restart Claude Desktop to load the new configuration.

🔐 Step 5: First-Time Authentication

5.1 Trigger OAuth Flow

  1. Open Claude Desktop

  2. Try any Google Analytics command, for example:

    "List all my Google Analytics properties"

5.2 Complete Authentication

  1. Browser opens automatically to Google OAuth page

  2. Sign in with your Google account (the one with Analytics access)

  3. Grant permissions by clicking "Allow"

  4. Browser shows success page

  5. Return to Claude - your command will complete automatically!

5.3 Verify Setup

After authentication, you should see:

  • A google_analytics_token.json file created in your project directory

  • Your Google Analytics properties listed in Claude's response

📖 Usage Examples

Property Management

"List all my Google Analytics properties" "Show me properties for account 123456789" "What GA4 properties do I have access to?"

Page View Analysis

"Get page views for property 421301275 from 2025-01-01 to 2025-01-31" "Show me top pages by page views for last month for property 421301275" "Analyze page performance by country for property 421301275"

User Analytics

"Get active users for property 421301275 in the last 7 days" "Show me user metrics by device category for property 421301275" "Compare new vs returning users for last month"

Traffic Source Analysis

"Analyze traffic sources for property 421301275 from 2025-01-01 to 2025-01-31" "Show me which channels drive the most users to my site" "Compare organic vs paid traffic performance"

Event Tracking

"Get events data for property 421301275 in the last 30 days" "Show me conversion events by source/medium" "Which events are most popular on my site?"

Custom Reports

"Create a report for property 421301275 with sessions, users, and page views by country from 2025-01-01 to 2025-01-31" "Run a custom report showing bounce rate and engagement rate by device category" "Generate a comprehensive traffic report with sessions, conversions, and revenue by source/medium"

🔍 Advanced GA4 Examples

Sessions and Users by Country

run_report( property_id="421301275", start_date="2025-01-01", end_date="2025-01-31", metrics=["sessions", "totalUsers", "screenPageViews"], dimensions=["country"], limit=20 )

Device Performance Analysis

run_report( property_id="421301275", start_date="2025-01-01", end_date="2025-01-31", metrics=["sessions", "bounceRate", "engagementRate"], dimensions=["deviceCategory", "operatingSystem"], limit=50 )

Traffic Sources with Conversions

run_report( property_id="421301275", start_date="2025-01-01", end_date="2025-01-31", metrics=["sessions", "conversions", "totalRevenue"], dimensions=["source", "medium", "campaignName"], limit=100 )

Daily Trend Analysis

run_report( property_id="421301275", start_date="2025-01-01", end_date="2025-01-31", metrics=["sessions", "activeUsers", "screenPageViews"], dimensions=["date"], limit=31 )

📁 Project Structure

google-analytics-mcp-server/ ├── server.py # Main MCP server ├── oauth/ │ ├── __init__.py # Package initialization │ └── google_auth.py # OAuth authentication logic ├── google_analytics_token.json # Auto-generated token storage (gitignored) ├── client_secret_[long-string].json # Your OAuth credentials (gitignored) ├── .env # Environment variables (gitignored) ├── .env.example # Environment template ├── .gitignore # Git ignore file ├── requirements.txt # Python dependencies ├── LICENSE # MIT License └── README.md # This file

🔒 Security & Best Practices

File Security

  • ✅ Credential files are gitignored - Never committed to version control

  • ✅ Local token storage - Tokens stored in google_analytics_token.json locally

  • ✅ Environment variables - Sensitive data in .env file

  • ✅ Automatic refresh - Minimal token exposure time

Recommended File Permissions

# Set secure permissions for sensitive files chmod 600 .env chmod 600 google_analytics_token.json chmod 600 client_secret_*.json

Production Considerations

  1. Use environment variables instead of .env files in production

  2. Implement rate limiting to respect API quotas

  3. Monitor API usage in Google Cloud Console

  4. Secure token storage with proper access controls

  5. Regular token rotation for enhanced security

🛠️ Troubleshooting

Authentication Issues

Issue

Symptoms

Solution

No tokens found

"Starting OAuth flow" message

✅ Normal for first-time setup - complete browser authentication

Token refresh failed

"Refreshing token failed" error

✅ Delete

google_analytics_token.json

and re-authenticate

OAuth flow failed

Browser error or no response

Check credentials file path and internet connection

Permission denied

"Access denied" in browser

Ensure Google account has Analytics access

Configuration Issues

Issue

Symptoms

Solution

Environment variables missing

"Environment variable not set"

Check

.env

file and Claude config

env

section

File not found

"FileNotFoundError"

Verify absolute paths in configuration

Module import errors

"ModuleNotFoundError"

Run

pip install -r requirements.txt

Python path issues

"Command not found"

Use absolute path to Python executable

Claude Desktop Issues

Issue

Symptoms

Solution

Server not connecting

No Google Analytics tools available

Restart Claude Desktop, check config file syntax

Invalid JSON config

Claude startup errors

Validate JSON syntax in config file

Permission errors

"Permission denied" on startup

Check file permissions and paths

API Issues

Issue

Symptoms

Solution

Invalid property ID

"Property not found"

Use numeric format:

421301275

API quota exceeded

"Quota exceeded" error

Wait for quota reset or request increase

Invalid date format

"Invalid date"

Use YYYY-MM-DD format:

2025-01-31

No data returned

Empty results

Check date range and property access

Debug Mode

Enable detailed logging for troubleshooting:

# Add to server.py for debugging import logging logging.basicConfig(level=logging.DEBUG)

🚀 Advanced Configuration

HTTP Transport Mode

For web deployment or remote access:

# Start server in HTTP mode python3 server.py --http

Claude Desktop config for HTTP:

{ "mcpServers": { "google-analytics": { "url": "http://127.0.0.1:8000/mcp" } } }

Custom Token Storage

Modify token storage location in oauth/google_auth.py:

# Custom token file location def get_token_path(): return "/custom/secure/path/google_analytics_token.json"

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone the repository git clone https://github.com/yourusername/google-analytics-mcp-server.git cd google-analytics-mcp-server # Create development environment python3 -m venv .venv source .venv/bin/activate # Install dependencies pip install -r requirements.txt # Set up development environment cp .env.example .env # Add your development credentials to .env

Making Changes

  1. Create a feature branch: git checkout -b feature/amazing-feature

  2. Make your changes with appropriate tests

  3. Test thoroughly with different property configurations

  4. Update documentation as needed

  5. Commit changes: git commit -m 'Add amazing feature'

  6. Push to branch: git push origin feature/amazing-feature

  7. Open a Pull Request with detailed description

📊 API Limits and Quotas

Google Analytics API Quotas

  • Core Reporting API: 100,000 requests per day per project

  • Realtime API: 10,000 requests per day per project

  • Request rate: 10 queries per second per project

Best Practices for API Usage

  1. Cache results when possible to reduce API calls

  2. Use appropriate date ranges to limit data volume

  3. Batch requests when supported

  4. Monitor usage in Google Cloud Console

  5. Implement retry logic for rate limit errors

Quota Management

# Monitor usage in Google Cloud Console # Go to APIs & Services → Quotas # Search for "Google Analytics" to see current usage

📄 License

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

MIT License

Copyright (c) 2025 Google Analytics MCP Server Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

📈 Roadmap

Upcoming Features

  • 🔄 Enhanced real-time analytics with streaming data

  • 📊 Built-in data visualization with charts and graphs

  • 🤖 AI-powered insights and anomaly detection

  • 📝 Custom dashboard creation tools

  • 🔍 Advanced segmentation capabilities

  • 🌐 Multi-property reporting

Made with ❤️ for the MCP community

Connect your Google Analytics 4 data directly to AI assistants and unlock powerful web analytics insights through natural language conversations.

This server cannot be installed

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

How are these scores calculated?

hybrid server

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

A FastMCP-powered server that connects Google Analytics 4 data to Claude Desktop with automatic OAuth 2.0 authentication, enabling users to access GA4 metrics, properties, and reports through natural language queries.

  1. 🌟 Open Source & Community
    1. GoMarble AI Open Source Projects
    2. Join Our Community
    3. 🚀 Try Our One-Click Integration
  2. ✨ Features
    1. 📋 Available Tools
      1. 🚀 Quick Start
        1. Prerequisites
      2. 🔧 Step 1: Google Cloud Platform Setup
        1. 1.1 Create Google Cloud Project
        2. 1.2 Enable Google Analytics APIs
        3. 1.3 Create OAuth 2.0 Credentials
      3. 🔧 Step 2: Google Analytics Access
        1. 2.1 Ensure Analytics Access
      4. 🔧 Step 3: Installation & Setup
        1. 3.1 Clone and Install
        2. 3.2 Environment Configuration
      5. 🖥️ Step 4: Claude Desktop Integration
        1. 4.1 Locate Claude Configuration
        2. 4.2 Add MCP Server Configuration
        3. 4.3 Restart Claude Desktop
      6. 🔐 Step 5: First-Time Authentication
        1. 5.1 Trigger OAuth Flow
        2. 5.2 Complete Authentication
        3. 5.3 Verify Setup
      7. 📖 Usage Examples
        1. Property Management
        2. Page View Analysis
        3. User Analytics
        4. Traffic Source Analysis
        5. Event Tracking
        6. Custom Reports
      8. 🔍 Advanced GA4 Examples
        1. Sessions and Users by Country
        2. Device Performance Analysis
        3. Traffic Sources with Conversions
        4. Daily Trend Analysis
      9. 📁 Project Structure
        1. 🔒 Security & Best Practices
          1. File Security
          2. Recommended File Permissions
          3. Production Considerations
        2. 🛠️ Troubleshooting
          1. Authentication Issues
          2. Configuration Issues
          3. Claude Desktop Issues
          4. API Issues
          5. Debug Mode
        3. 🚀 Advanced Configuration
          1. HTTP Transport Mode
          2. Custom Token Storage
        4. 🤝 Contributing
          1. Development Setup
          2. Making Changes
        5. 📊 API Limits and Quotas
          1. Google Analytics API Quotas
          2. Best Practices for API Usage
          3. Quota Management
        6. 📄 License
          1. MIT License
        7. 📈 Roadmap
          1. Upcoming Features

        Related MCP Servers

        • mcp-server-google-analytics

          ruchernchong
          -
          security
          A
          license
          -
          quality
          An MCP server implementation for accessing Google Analytics 4 (GA4) data, built using the Model Context Protocol TypeScript SDK.
          Last updated -
          5
          56
          67
          MIT License

        • Choose MCP Server

          keurcien
          -
          security
          F
          license
          -
          quality
          An MCP server for Claude Desktop that allows users to query data from selected Google Cloud datasets by configuring project ID and datasets in the Claude Desktop configuration.
          Last updated -
          • Apple

        • Google Analytics MCP Server

          surendranb
          -
          security
          F
          license
          -
          quality
          Connects Google Analytics 4 data to Claude, Cursor and other MCP clients, enabling natural language queries of website traffic, user behavior, and analytics data with access to 200+ GA4 dimensions and metrics.
          Last updated -
          140

        • Google Campaign Manager 360 MCP Server by CData

          CDataSoftware
          -
          security
          A
          license
          -
          quality
          This read-only MCP Server allows you to connect to Google Campaign Manager 360 data from Claude Desktop through CData JDBC Drivers. Free (beta) read/write servers available at https://www.cdata.com/solutions/mcp
          Last updated -
          MIT License
          • Apple
          • Linux

        View all related MCP servers

        Appeared in Searches

        New 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/gomarble-ai/google-analytics-mcp-server'

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