How to Use the Google Analytics MCP in Pydantic AI

Q: Can my pydantic-ai agent discover Google Analytics metadata via MCP?

Yes, the agent uses getmetadata to inspect the available metrics and dimensions for your property. The returned schema is validated at runtime, ensuring your agent only queries valid fields.

Q: How do I list my GA4 properties using this toolset?

Your agent runs listproperties to retrieve all properties under your account. The returned list of property configurations is parsed into typed Python objects for safe reference in subsequent queries.

Validate every Google Analytics API response at runtime using type-safe Pydantic AI agent workflows.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Google Analytics MCP to Pydantic AI

Create your Vinkius account to connect Google Analytics to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Google Analytics with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe data fetching with Pydantic AI MCP Server

This MCP Server enforces strict schema validation on every GA4 API response before your agent processes the data. When the agent calls `run_report`, the returned metrics are validated against your Pydantic models to catch malformed fields immediately. If the GA4 API returns unexpected null values or altered dimension formats, the Pydantic AI framework raises a validation error at runtime. This prevents your downstream dashboard pipelines from consuming corrupted data without warning.

Verify GA4 dimension compatibility

The `check_compatibility` tool allows your agent to programmatically verify if your selected metrics and dimensions can be combined. Running this check before executing complex reports prevents the API from throwing unhandled schema errors. Once compatibility is confirmed, the agent runs `batch_run_reports` to pull structured analytics data. The type-safe environment ensures that the resulting nested JSON arrays map perfectly to your Python classes.

Audit user journeys with strict typing

The `get_user_activity` tool retrieves chronological event streams for specific user IDs directly into your agent's validation loop. The framework checks that pageviews and conversion events conform to your expected schemas. For broader trends, the agent calls `run_funnel_report` to dissect conversion drop-offs. The structured funnel steps are parsed into typed models, making it easy to feed clean data into your local machine learning pipelines.

Setup guide

Set up Google Analytics MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "google-analytics-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Google Analytics tools.",
)

result = await agent.run("List recent Google Analytics transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Google Analytics 4. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Google Analytics now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Google Analytics MCP in Pydantic AI

Initialize MCPToolset with your Vinkius HTTP URL and pass it to your Agent's toolsets argument. This registers GA4 tools like `run_report` and automatically handles runtime parameter validation.

If the GA4 API returns an error or incompatible dimensions, the framework raises a validation exception. This fail-fast behavior prevents your agent from hallucinating metrics or passing empty reports to your application.

Yes, the agent uses `get_metadata` to inspect the available metrics and dimensions for your property. The returned schema is validated at runtime, ensuring your agent only queries valid fields.

Your agent runs `list_properties` to retrieve all properties under your account. The returned list of property configurations is parsed into typed Python objects for safe reference in subsequent queries.

All GA4 real-time reports, user activity logs, and property configurations are processed in isolated, single-use V8 sandboxes. Vinkius handles the authorization layer securely, meaning your raw API tokens are never exposed to the agent or stored in plaintext.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript