Skip to content

About

Google Analytics MCP (GA4 MCP) server for Claude, Claude Code and Cursor: traffic sources, channel comparison, converting organic landing pages, engagement and key events. Read-only configs for the open-source Semust MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Google Analytics MCP Server

Semust Google Analytics MCP server: GA4 traffic, channels and conversions for Claude and Cursor

Get API key Documentation Main server: semust-mcp License: MIT

The Google Analytics MCP server (a GA4 MCP) connects your Google Analytics 4 property to Claude, Claude Code and Cursor. Ask where your traffic comes from, which landing pages convert and which channels are growing, without building GA4 explorations.

Six data tools return the overview, traffic sources, pages, geography, devices and key events. Four ready-made analyses read traffic trends, organic landing page conversions, channel shifts and engagement for you. It is part of Semust, the SEO and analytics platform behind the data.

Note

This repository contains no server code. It is a ready-made setup for the open-source Semust MCP server that loads only the 11 tools you need here, with SEMUST_MCP_TOOLSETS=ga. Copy a config from configs/, add your key and path, and restart your client.

What you can ask

Type these as they are or in your own words. The assistant picks the tool itself.

  • Which traffic channels grew and which shrank compared with last month?
  • Which 10 landing pages bring the most form_submit events from organic search?
  • List my pages with high traffic but low engagement.
  • What were my busiest and quietest days in the last 90 days? Does traffic drop on weekends?
  • Which cities do most of my visitors come from?
  • What share of my users are on mobile versus desktop?
  • Which UTM campaigns brought the most sessions this month?
  • How many people are on the site right now?

prompts.md has 16 copy-paste prompts, grouped by task.

The question "Which pages convert visitors from organic search, and which get traffic but no conversions?" and the Semust MCP tools an assistant calls to answer it

How it works

Claude or Cursor calls the semust-mcp server on your computer, which loads 11 tools with SEMUST_MCP_TOOLSETS=ga. The server calls the Semust API with your MCP key, and Semust reads Google Analytics 4.

Your assistant talks to the Semust MCP server on your computer. With SEMUST_MCP_TOOLSETS=ga the server registers 11 tools: list_projects, six GA4 data tools and four analyses. Each call goes to the Semust API with your MCP key, and Semust reads the GA4 property connected to your project.

Setup

Setup takes about five minutes: create a key, download the server once, then paste one config.

1. Create an MCP key

Log in to Semust and open Settings → MCP Setup. Create an MCP key: it starts with smk_ and is shown only once, so copy it straight away. A key can reach all your projects or just one, expires after 30, 90 or 365 days, and can be renewed or revoked on the same page.

Leave "Can post to social media" switched off. The tools in this server only read data, and a read-only key is all they need.

2. Install the Semust MCP server

This repository holds the setup, not the server. Download the open-source Semust MCP server once and install its three dependencies:

git clone https://github.com/Semust-com/semust-mcp.git
cd semust-mcp
pip install -r requirements.txt   # use pip3 if pip is not found
pwd                               # prints the folder; the config below needs its absolute path

Prefer a virtual environment? Run python3 -m venv .venv && .venv/bin/pip install -r requirements.txt instead, and use /absolute/path/to/semust-mcp/.venv/bin/python as the command in the configs below. Your server then keeps working whatever happens to your system Python.

Important

SEMUST_MCP_TOOLSETS needs semust-mcp 1.9.0 or newer. An older copy ignores it and loads every tool, so run git pull in the semust-mcp folder if you installed it before.

3. Add it to your AI client

Client Ready-made file
Claude Desktop configs/claude_desktop_config.json
Claude Code configs/claude-code.sh
Cursor configs/cursor-mcp.json

In each, replace your-api-key-here with your MCP key and /absolute/path/to/semust-mcp/semust_mcp.py with the real path from step 2.

Claude Desktop

Add this to claude_desktop_config.json (full guide):

{
  "mcpServers": {
    "semust": {
      "command": "python3",
      "args": [
        "/absolute/path/to/semust-mcp/semust_mcp.py"
      ],
      "env": {
        "SEMUST_API_KEY": "your-api-key-here",
        "SEMUST_MCP_TOOLSETS": "ga"
      }
    }
  }
}
Where is claude_desktop_config.json?
System Folder
macOS ~/Library/Application Support/Claude/ (Finder → Cmd+Shift+G)
Windows %APPDATA%\Claude\
Windows (Microsoft Store) %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\

If the file is not there yet, create it. If it already has other servers, add the "semust" entry inside the existing "mcpServers" object instead of pasting a second one.

Windows, or python3 not found?
  • The path in args must be absolute. Claude Desktop does not expand ~.
  • On Windows use "command": "python" and a path with double backslashes, such as "C:\\Users\\you\\semust-mcp\\semust_mcp.py". If python is not recognised, give the full path to python.exe.
  • On macOS and Linux there is often no python, only python3. Run which python3 and use the full path it prints if the server does not start.

You do not need SEMUST_BASE_URL: the server already points at the Semust API.

Restart the client completely after editing the file. On macOS press Cmd+Q; on Windows quit from the system tray icon. Closing the window is not enough.

Claude Code

Claude Code registers servers from the command line, so there is no file to edit:

claude mcp add --scope user semust \
  -e SEMUST_API_KEY=your-api-key-here \
  -e SEMUST_MCP_TOOLSETS=ga \
  -- python3 /absolute/path/to/semust-mcp/semust_mcp.py

--scope user makes the server available in every project. To keep the key out of your shell history, put SEMUST_API_KEY and SEMUST_MCP_TOOLSETS in a .env file next to semust_mcp.py instead and leave out the -e flags; the server reads that file on startup.

Cursor

Copy the contents of configs/cursor-mcp.json into ~/.cursor/mcp.json to use the server in every project, or into .cursor/mcp.json inside one project. You can also add it from Cursor's settings as a stdio server with the same command, path and environment (Cursor guide).

Other MCP clients

Any client that runs stdio MCP servers works: command python3 (or python on Windows), argument the absolute path to semust_mcp.py, and the environment variables SEMUST_API_KEY and SEMUST_MCP_TOOLSETS=ga. See other MCP clients.

4. Check that it works

Open a new chat and ask "Show me my Semust projects". The assistant calls list_projects and lists your projects with the integrations each one has connected. Claude Desktop shows the semust server with 11 tools in its tools menu; in Claude Code, claude mcp list should report semust as connected and /mcp lists the tools.

Adding more Semust tools later

SEMUST_MCP_TOOLSETS takes a comma-separated list, so one server can cover several sources: for example "gsc,ga,gads" for Search Console, Analytics and Ads together. list_projects is always included. Unset, empty or all loads all 82 tools, and a misspelt family name also loads everything (with a warning), so a typo never hides tools.

Family Tools Family Tools
gsc Google Search Console data and reports ym Yandex Metrica
ga Google Analytics 4 bing Bing Webmaster
gads Google Ads metrik Semust Metrik web analytics
rank Rank Tracker changes Change Monitor
aiRank AI Overview Tracker competitor Competitor Analysis
indexing Index Monitor social LinkedIn, Facebook and Instagram posting

Tools in this server

With SEMUST_MCP_TOOLSETS=ga the server registers these 11 tools. Every parameter is documented in the linked reference pages.

Always loaded · projects reference

Tool What it does
list_projects Lists your projects and which integrations each one has connected.

Google Analytics data · Google Analytics data reference

Tool What it does
ga_get_overview Core GA4 metrics such as users, sessions, engagement and conversions.
ga_get_traffic_sources Traffic broken down by channel, source and medium.
ga_get_pages Views, engagement and exits per page.
ga_get_geo Visitors by country and city.
ga_get_devices Device, browser and operating system breakdown.
ga_get_key_events Key events (conversions) and their counts.

Google Analytics reports · Google Analytics reports reference

Tool What it does
ga_report_traffic_trends Daily traffic trend: growth, peak and trough days, weekday vs weekend.
ga_report_landing_page_performance The landing pages that drive the most conversions from organic search.
ga_report_channel_comparison Compares channels with the previous period: which are growing and which are falling.
ga_report_engagement_analysis Sorts pages into high, medium and low engagement tiers.

Requirements

  • Python 3.10 or newer and semust-mcp 1.9.0 or newer.
  • An MCP client: Claude Desktop, Claude Code, Cursor or any client that runs stdio servers.
  • A Semust account with an active plan; the trial counts.
  • Google Analytics 4 connected to the project in Semust: open the project, then Project Settings → Integrations. Each project uses its own GA4 property.
  • Key events marked in GA4 if you want conversion answers.

Security

Every tool in this server only reads data. Nothing can change your GA4 property, its events or its settings.

  • The server runs on your computer. It is a local process that your AI client starts, not a hosted service.
  • Your key stays on your machine. It lives in your client config or in a .env file next to semust_mcp.py, and is only sent to the Semust API. Claude, Cursor and Anthropic never see it; they only see the data returned for your question.
  • HTTPS only. The server refuses to start if its API address is plain http:// (other than localhost), so the key is never sent in clear text.
  • Protect your config file. Anyone who can read claude_desktop_config.json or ~/.cursor/mcp.json can read the key in it. Never commit those files; this repository's .gitignore already excludes .env.
  • Limit and revoke. Tie a key to one project, choose a 30, 90 or 365-day expiry, and revoke it in Settings → MCP Setup at any time.
  • Third-party text is data. Results can contain text written by others, such as search queries or page titles. An AI model may follow instructions hidden in such text; that is true of every MCP server that surfaces outside data. Read your assistant's suggestions before acting on them.

More detail: Semust MCP security guide.

Troubleshooting

Problem Fix
The server does not appear Quit the client completely and reopen it. Check that the path in args is absolute and that python3 runs in a terminal.
You see all 82 tools, not 11 Your semust-mcp copy is older than 1.9.0. Run git pull in its folder and restart the client.
"Invalid API key" (401) Copy the key again from Settings → MCP Setup; it may have expired or been revoked.
"User not active" (403) The Semust account needs an active plan or trial.
"... not connected" Connect the integration for that project in Semust, then ask again.
No module named 'mcp.server.fastmcp' Update semust-mcp (git pull) and run pip install -U -r requirements.txt.

More fixes: Semust MCP troubleshooting.

FAQ

What is a Google Analytics MCP server?

It is a connection that lets Claude read your GA4 data through the Model Context Protocol. The Semust GA4 MCP has 10 tools: six for raw data and four ready-made analyses, plus list_projects.

Do I need a Google Cloud project or a service account?

No. You connect GA4 to your Semust project once and Semust handles Google authorization. You only put your Semust MCP key in the client config.

How fresh is the data?

GA4 reports run about one day behind, so the assistant uses yesterday as the latest date. The number of users on the site right now comes in real time with the overview.

Why do the conversion tools come back empty?

Most likely no key events are set up in GA4 yet. Once you mark an event as a key event in GA4, conversions from then on show up in the answers. The landing page analysis also looks at organic search sessions only, because it measures what SEO contributes.

Is this a separate MCP server?

No. There is one Semust MCP server, semust-mcp. This repository is its setup for Google Analytics 4: SEMUST_MCP_TOOLSETS tells it to register only these tools, so your assistant spends less context on tool descriptions and picks the right tool more often. Change the value at any time to load more.

Does it cost anything?

The Semust MCP server is free and open source under the MIT license. The data it reads needs an active Semust plan, and the trial counts.

Learn more

Related repositories

SEO data APIs

Repository What it does Product page
google-serp-scraper Organic results, People Also Ask, AI Overviews, ads and more as JSON Google SERP API
google-images-scraper Google Images results with titles, source pages and image URLs Google Images API
youtube-scraper YouTube search, video details, transcripts and comments YouTube API
google-trends-scraper Interest over time, regions, related queries and demographics Google Trends API
google-business-scraper Google Business profiles, local search and reviews Google Business Data API
keyword-research-api Search volume, CPC, competition, intent and related keywords Keyword Research API
backlinks-api Backlinks, referring domains, anchors and link history Backlinks API
domain-research-api Organic keywords, competitors, top pages and keyword gaps for any domain Domain Research API
technical-seo-api 27 technical SEO checks for any URL in one call Technical SEO API
lighthouse-on-page-api Lighthouse scores, on-page audits and page content extraction Lighthouse & On-Page API

MCP servers for AI assistants

Repository What it does Product page
semust-mcp One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting Semust MCP Server
seo-mcp Search Console, rank tracking, indexing and competitor tools for AI assistants SEO MCP
google-search-console-mcp Ask your AI assistant about clicks, queries and pages Google Search Console MCP
google-ads-mcp Campaigns, search terms and spend in your AI assistant Google Ads MCP
rank-tracker-mcp Keyword rankings and AI-search visibility for AI assistants Rank Tracker MCP
web-analytics-mcp Privacy-friendly first-party analytics in your AI assistant Web Analytics MCP
bing-webmaster-mcp Bing queries, pages, links and crawl issues Bing Webmaster MCP
yandex-metrica-mcp Yandex Metrica traffic and search phrases Yandex Metrica MCP
social-media-mcp Draft and schedule LinkedIn, Facebook and Instagram posts Social Media MCP

Support

Found a problem with an example? Open an issue.

License

The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

About

Google Analytics MCP (GA4 MCP) server for Claude, Claude Code and Cursor: traffic sources, channel comparison, converting organic landing pages, engagement and key events. Read-only configs for the open-source Semust MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages