Skip to content

Query Traffic With Mcp

📖 The Legend Behind This Quest

Your agent can reach Google Analytics now — but a connection without good questions is just a faster way to be confused. In this quest you'll learn the five tools the MCP server exposes, the GA4 vocabulary of dimensions and metrics, and how to turn "how's traffic?" into a precise, repeatable report.

🎯 Quest Objectives

Primary Objectives (Required for Quest Completion)

  • Run a top-pages report for a date range
  • Segment sessions by channel
  • Apply a dimension filter to narrow a report

Secondary Objectives (Bonus Achievements)

  • Compare two date ranges in one report (week-over-week)
  • Ask your agent a plain-English question and read its query back

Mastery Indicators

  • You can name the five tools and pick the right one quickly
  • You can build a runReport call from a question in your head

🗺️ Quest Prerequisites

📋 Knowledge Requirements

🛠️ System Requirements

  • The google-analytics MCP server connected to your agent

🧰 Chapter 1: Know Your Five Tools

The MCP server exposes five tools. Four are convenience wrappers; one is the workhorse.

Tool Use it for
getActiveUsers quick active-user count
getPageViews page views, optionally by a dimension
getEvents event counts
getUserBehavior session duration, bounce/engagement
runReport anything — custom dimensions + metrics + filters

When in doubt, reach for runReport. The others are shortcuts for common questions.

📐 Chapter 2: Dimensions vs. Metrics

Every report is metrics (numbers) grouped by dimensions (attributes).

  • Metrics: activeUsers, sessions, screenPageViews, engagementRate, averageSessionDuration
  • Dimensions: pagePath, pageTitle, sessionDefaultChannelGroup, country, deviceCategory, hostName, date

A report = "give me these metrics, broken down by these dimensions, for this date range."

🔎 Chapter 3: Build Real Reports

Just ask your agent: "Top 10 pages by views over the last 28 days." Behind the scenes it calls runReport:

runReport({
  dateRanges: [{ startDate: "28daysAgo", endDate: "today" }],
  dimensions: [{ name: "pagePath" }],
  metrics: [{ name: "screenPageViews" }, { name: "activeUsers" }],
  orderBys: [{ metric: { metricName: "screenPageViews" }, desc: true }],
  limit: 10,
})

Traffic by channel — where visitors come from:

runReport({
  dateRanges: [{ startDate: "28daysAgo", endDate: "today" }],
  dimensions: [{ name: "sessionDefaultChannelGroup" }],
  metrics: [{ name: "sessions" }, { name: "engagementRate" }],
})

Week-over-week — two date ranges in one report:

dateRanges: [
  { startDate: "7daysAgo",  endDate: "today",     name: "cur" },
  { startDate: "14daysAgo", endDate: "8daysAgo",  name: "prev" },
]

Filter to one slice — e.g. only one section of the site:

dimensionFilter: { filter: { fieldName: "pagePath",
  stringFilter: { matchType: "BEGINS_WITH", value: "/quests/" } } }

🧪 Chapter 4: Sanity-Check Before You Trust

One habit pays for itself forever: before believing a headline number, group by hostName once. It instantly reveals whether localhost, Docker, or another site is mixed into your data — so you analyze production traffic, not your own dev machine. Add this filter to keep reports honest:

dimensionFilter: { filter: { fieldName: "hostName",
  stringFilter: { matchType: "EXACT", value: "your-site.dev" } } }

✅ Validation

  • You produced a top-pages report and a channel report
  • You filtered a report by a dimension value
  • You can explain when to use runReport vs. the wrappers

🏆 Rewards

  • 🏆 Report Runner — you build reports on demand
  • 📊 Dimension Wrangler — dimensions and metrics are second nature

➡️ Next Quest

Running reports by hand gets old. Put it on autopilot in Automate a Weekly Traffic Report.