How to set up the Model Context Protocol (MCP) server for GA4

The following guide demonstrates configuring an MCP server for GA4. You can alternatively configure the MCP server for Stape or for GTM.

The setup involves:

1. Configuring Python.
2. Enabling required APIs in Google Cloud.
3. Setting credentials for Google Analytics API access.
4. Connecting Gemini to your Google Analytics setup.

This article offers two guides on setting up MCP for GA4:

1. Shorter guide for advanced users. If you know your way around Python, Google Cloud projects, and Gemini CLI, use this.
2. Step-by-step instructions for newcomers. If you don’t understand something from the shorter guide, choose this path.

Requirements for setting up MCP for GA4

• Access to a configured GA4 account.

Guide to configuring MCP for GA4 for advanced users

1. Configure Python with pipx

Install pipx for your platform.

2. Enable APIs in Google Cloud

Follow this guide to enable APIs in your Google Cloud project:

• Google Analytics Admin API
• Google Analytics Data API
• Gemini for Google Cloud API

3. Configure credentials

Configure your Application Default Credentials (ADC). Make sure the credentials are for a user with access to your Google Analytics accounts or properties.

Credentials must include the Google Analytics read-only scope: https://www.googleapis.com/auth/analytics.readonly 

Check out Manage OAuth Clients for how to create an OAuth client.

When the gcloud auth application-default command completes, copy the PATH_TO_CREDENTIALS_JSON file location printed to the console in the following message. You'll need this for the next step!

4. Configure Gemini

1. Install Gemini CLI or Gemini Code Assist.

2. Create or edit the file at ~/.gemini/settings.json, adding your server to the mcpServers list.

Replace PATH_TO_CREDENTIALS_JSON with the path you copied in the previous step. We also recommend that you add a GOOGLE_CLOUD_PROJECT attribute to the env object. Replace YOUR_PROJECT_ID in the following example with the project ID of your Google Cloud project.

Step-by-step guide to configuring MCP for GA4 for beginners

The following instructions show how to set up MCP for GA4 on Windows. You can adapt the same steps for other platforms, using this guide as an example.

1. Configure Python with pipx

First, we’ll need to install pipx for your platform. Choose one of the following installation methods based on what you already have:

Method 1: Install via Scoop (easier if you have Scoop)

Scoop is a program installer for Windows. If you don't already have it, or you’re using a different platform, this method might not be for you - skip to Method 2 instead.

Step 1: Open PowerShell or Command Prompt

• Press the Windows key on your keyboard.
• Type powershell or cmd.
• Click on "Windows PowerShell" or "Command Prompt" when it appears.
• A black or blue window with text will open - this is your terminal.

Step 2: Type the installation command

• In the terminal, type exactly: scoop install pipx.
• Press Enter.
• Wait while it downloads and installs (you'll see text scrolling by).

Step 3: Set up the path

• When it finishes, type: pipx ensurepath.
• Press Enter.
• This tells Windows where to find pipx when you want to use it later.

Step 4: Restart your terminal

• Close the PowerShell/Command Prompt window and open it again (repeat Step 1).

Done! To upgrade pipx later, open PowerShell/Command Prompt and type scoop update pipx.

Method 2: Install via pip (Most common method)

Python must already be installed on your computer. If you're not sure, check if you have Python:

• Press the Windows key.
• Type cmd.
• Click Command Prompt.
• Type python --version or py --version and press Enter.
• If you see a version number (like "Python 3.12.0"), you have Python! Continue below.
• If you see an error, follow this guide to install Python.

Step 1: Open Command Prompt

• Press the Windows key on your keyboard.
• Type cmd.
• Click on "Command Prompt" when it appears.
• A black window will open.

Step 2: Install pipx

• In the black window, type this command: py -m pip install --user pipx (if you installed Python from the Microsoft Store, use python3 instead of py).
• Press Enter.
• You'll see text scrolling as it downloads and installs. Wait until you see a new line where you can type again.

Step 3: Look for a warning message

• After installation, you might see a yellow WARNING message that says something like: WARNING: The script pipx.exe is installed in C:\Users\YourName\AppData\Roaming\Python\Python3x\Scripts which is not on PATH
• Don't panic! This is normal. Write down or remember that folder path (the part that looks like C:\Users\...)

Step 4: Navigate to the Scripts folder

• In the same Command Prompt window, type cd followed by the path from the warning, for example: cd C:\Users\YourName\AppData\Roaming\Python\Python311\Scripts. You can usually copy the path from the warning message.
• Press Enter.

Step 5: Run ensurepath

• Now type exactly: .\pipx.exe ensurepath
• The .\ at the beginning is important - don't forget it!
• Press Enter.
• This command tells Windows where to find pipx in the future.

Step 6: Restart Command Prompt

• Close the Command Prompt window and reopen it.

Step 7: Verify it works

• Type pipx and press Enter.
• If you see information about pipx commands, it worked!
• If you see "pipx is not recognized," try restarting your computer and trying again.

To upgrade pipx later:

• Open Command Prompt.
• Type: py -m pip install --user --upgrade pipx.
• Press Enter.

2. Enable APIs in Google Cloud

APIs are like doorways that let programs talk to Google Analytics. You need to unlock these doorways first.

Step 1: Go to Google Cloud Console

• Go to: https://console.cloud.google.com.
• Sign in with your Google account if asked.

Step 2: Select or Create a Project

• At the top of the page, you'll see a dropdown menu that shows a project name if you already have a project. Click on its name.
• If you don’t have a project, create it:
  • Click New Project.
  • Type a descriptive project name. Under Location, select a parent organization that you have access to, or select No organization.
  • Click Create. Wait a few seconds for it to be created.

Step 3: Enable the required APIs

• On the left side of the screen, look for a menu (three horizontal lines ☰ if it's collapsed) → click APIs & Services → click Library.
• You'll see a search box at the top that says "Search for APIs and Services" → type Google Analytics Admin API.
• You'll see a page with information about this API - click the Enable button.
• Wait a few seconds while it enables (the button will change).
• Repeat this step to search and install Google Analytics Data API and Gemini for Google Cloud API.

3. Configure credentials

Credentials are IDs that prove you have permission to access Google Analytics data. There are two main ways to set this up.

Step 1: Create an OAuth Client

1. Go to the Credentials Page

• In Google Cloud Console, click the menu (☰) on the left.
• Click APIs & Services → Credentials.

2. Create OAuth Consent Screen

• If you see a message Remember to configure the OAuth consent screen…, click Configure consent screen and go through project configuration by following on-screen instructions.

3. Create OAuth Client ID

• Click APIs & Services → Credentials.
• Click the Create credentials button at the top → select OAuth client ID. 

• For application type, choose Desktop app. Give it a descriptive name → click Create.
• A popup will show your Client ID and Client Secret. Click Download JSON and save this file somewhere on your computer. This is important, you'll need this file soon. Then click OK to close the popup.

4. Configure the scope

• Click APIs & Services → OAuth Consent Screen → Data Access.
• Click Add or remove scopes.
• Scroll down to the Manually add scopes section. Type https://www.googleapis.com/auth/analytics.readonly and click Add to table. Then find this scope in the table above, enable it, and click the Update button.

5. Add a test user

• Until your Google Cloud project stays unpublished (in the testing status), anyone using the MCP for GA4 setup (including yourself) will have to do it with an email that has been added to the list of test users.
• Click APIs & Services → OAuth Consent Screen → Audience.
• In the Test users section, click Add users.
• Add emails that should have access to the MCP setup and click Save.

Step 2: Install Google Cloud SDK

gcloud is a command-line tool that lets you talk to Google Cloud from your computer's terminal.

1. Download and install Google Cloud SDK

• Go to: https://cloud.google.com/sdk/docs/install.
• Click on the Windows tab and click the download link for the Google Cloud CLI installer (if using a different OS, click on the respective tab and follow its instructions).
• Run the downloaded file and install the SDK (once completed, make sure that Start Google Cloud SDK Shell is checked).

2. Initialize gcloud

• A new window called Google Cloud SDK Shell will open automatically if you checked that option.
• When asked You must log in to continue. Would you like to log in (Y/n)?, type Y and press Enter.
• Your web browser will open, asking you to sign in to Google. Sign in with your Google account that you’ve added as a test user at step 1. Grant Google Cloud SDK access to your account. You may see the notification saying something like Connection not safe - this happens because the project is in test mode. In that case, click Advanced and manually select the services to grant access to.
• Go back to the Google Cloud SDK Shell window. It will ask you to pick a project. Type the number next to your project name and press Enter.

Step 3: Set Up Application Default Credentials (ADC)

ADC is the main ID card that programs will use to access Google Analytics on your behalf.

1. In Google Cloud SDK Shell, navigate to your client JSON file.

• Remember where you saved that JSON file in Step 1? Let's say you saved it in C:\Users\YourName\Documents and it's named client_secret_123.json.
• In the SDK Shell, type cd followed by the folder path, e.g.: cd C:\Users\YourName\Documents and press Enter.

2. Run the Authentication Command

• Now type this command (all on one line): gcloud auth application-default login --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform --client-id-file=client_secret_123.json
• Replace client_secret_123.json with your actual file name. Also, make sure to enter the full name, including the file’s extension.
• Press Enter.

3. Complete the Authentication

• Your web browser will open again. Sign in with your Google account if asked.
• You'll see a page asking for permissions - click Allow.

4. Find your Credentials Path

• Go back to the SDK Shell. You'll see a long message. The important part says: Credentials saved to file: [C:\Users\YourName\AppData\Roaming\gcloud\application_default_credentials.json]
• Copy this entire path! You'll need it for your program (you can right-click and select Mark, highlight the path, then right-click again to copy).

How to verify it worked:

• In Google Cloud SDK Shell, type: gcloud auth application-default print-access-token
• Press Enter.
• If you see a long string of random characters, it worked!
• If you see an error, try the authentication steps again.

4. Configure Gemini

This step connects Gemini (an AI tool by Google) to your Google Analytics setup so it can access your data.

Step 1. Install Node.js

• Gemini CLI is a Node.js project, not a Python project, so we’ll need Node.js to install it. To do it, go to: https://nodejs.org/. Download and install the LTS (Long Term Support) version.
• To verify Node.js is installed, in Google Cloud SDK Shell (or any Command Prompt) type: node --version and press Enter. You should see a version number like v20.10.0.

Step 2: Install Gemini CLI from npm

• In Command Prompt, type: npm install -g @google/gemini-cli and press Enter.
• Wait while it installs.
• Verify it installed. Type: gemini --version and press Enter. You should see a version number.

Step 3: Create or edit the settings file

This is a configuration file that tells Gemini where to find your credentials and how to connect to Google Analytics.

• Press Windows key + E to open File Explorer. In the address bar, enter %USERPROFILE% and press Enter. This takes you to your user home folder (like C:\Users\YourName).
• At the top of File Explorer, click the View tab. Check the box that says Hidden items. Now that you see hidden files, look for the .gemini folder (it starts with a dot). If you don’t see it, you need to create it:
  • Right-click in the empty space of File Explorer and click New → Folder.
  • Name it .gemini (with the dot at the beginning) and press Enter.
• Open the .gemini folder. Look for a file named settings.json. If you don’t see it, create it:
  • Right-click in the empty space and click New → Text Document.
  • Name it settings.json (make sure it ends in .json, not .txt) and press Enter.
• Right-click on the settings file and select Open with → Notepad.

Step 4: Add your configuration

• Paste the following configuration:

• Replace the placeholders:
  • C:\\Users\\YourName\\AppData\\Roaming\\gcloud\\application_default_credentials.json - remember the path where the credentials were saved at Step 3.4? Use it here.
  • my-project-12345 - go to https://console.cloud.google.com and look for your project name. Next to it, you'll see Project ID with a code like my-project-12345. Use it here.
• Save the file and close Notepad.

Step 5. Launch Gemini CLI

• Open Command Prompt or Google Cloud SDK Shell.
• Type set GOOGLE_CLOUD_PROJECT=client_secret_123.json, where client_secret_123.json should be replaced with the full name of the JSON file you downloaded when configuring credentials. This sets your project ID that you used in the settings.json file.
• Type gemini and press Enter. In a few seconds, you should see Gemini CLI running.
• Select the Login with Google option and click Enter. Go through the Google Authorization process and return to Gemini CLI.

Congratulations, your MCP for GA4 setup is complete and ready to go!

Testing MCP for GA4

Launch Gemini CLI and type /mcp. You should see analytics-mcp listed in the results.

Here are some sample prompts to get you started:

1. what can analytics-mcp do?
2. provide details for my Google Analytics property containing 'xyz' in its name.
3. list the top events by user engagement in my Google Analytics property over the last 30 days.
4. what percentage of users in the past six months were logged in?
5. show all custom dimensions and custom metrics defined in my Google Analytics property.