How to Use Umami Analytics With Your AI Agent Using MCP

Updated: September 2026

Umami Analytics can now connect directly to AI tools through the Model Context Protocol (MCP), giving your AI agent access to your website analytics through natural language.

Instead of opening your analytics dashboard every time you want to investigate your traffic, you can ask an AI agent questions such as:

How many visitors did my website get last week?
What were my most popular pages this month?
Where is my traffic coming from?
What happened when traffic suddenly spiked?
Which pages have the worst Core Web Vitals on mobile?
How is my checkout funnel performing?

Umami Cloud provides a remote MCP server that makes this possible. The connection is read-only, uses your existing Umami permissions, and communicates with Umami through the same Cloud API used by the dashboard.

This guide explains how to connect an AI client to Umami Analytics and what you can do once the connection is established.

What Is MCP?

The Model Context Protocol, or MCP, is a standard that allows AI applications to connect to external tools and data sources.

In this case, MCP allows an AI agent to communicate with Umami Cloud and retrieve analytics data when you ask a question.

The important part is that the AI agent isn’t given direct access to your underlying analytics database. The Umami MCP server calls the Umami Cloud API on your behalf and respects the website and team permissions associated with your account.

All available MCP tools are read-only.

That means an AI agent can analyze your analytics, but it can’t use MCP to modify your Umami data.

What You Need

To connect an AI agent to Umami Cloud using MCP, you’ll need:

An Umami Cloud account with access to the website you want to analyze
An Umami Cloud API key
An MCP-compatible AI client
A client that supports API-key or Bearer-header authentication

The same subscription requirements and rate limits that apply to the Umami Cloud API also apply when using MCP.

The Umami MCP Endpoint

The remote MCP server is available at:

https://cloud.Your-Umami-Domain/mcp

Your AI client connects to this endpoint and authenticates using an Umami Cloud API key.

The API key should be passed using the Authorization header with the Bearer authentication scheme:

Authorization: Bearer api_<your-cloud-api-key>

Some clients can instead use the x-umami-api-key header:

x-umami-api-key: api_<your-cloud-api-key>

If you provide both headers, they must contain the same API key.

Creating an API Key

Before configuring your AI agent, create an API key in Umami Cloud.

Once you have your key, keep it private. Treat it like a credential that grants access to the analytics available through your Umami account.

Your AI client will use this key whenever it communicates with the Umami MCP server.

Connecting an AI Client

Most modern MCP clients that support remote servers allow you to specify a server URL and custom HTTP headers.

For example, a client such as Claude Desktop or Cursor can use a configuration like this:

{
  "mcpServers": {
    "umami": {
      "url": "https://cloud.Your-Umami-Domain/mcp",
      "headers": {
        "Authorization": "Bearer api_<your-cloud-api-key>"
      }
    }
  }
}

Replace api_<your-cloud-api-key> with your actual Umami Cloud API key.

Once the MCP server has been added and authenticated, your AI client can use the available Umami tools to retrieve analytics information.

The exact configuration interface varies between AI clients, so check your client’s MCP configuration options if the format differs.

Using Umami With Clients That Only Support Local MCP Servers

Not every MCP client supports connecting directly to a remote server.

If your client only supports local stdio MCP servers, you can run the Umami MCP package locally using npx:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_API_KEY": "api_<your-cloud-api-key>"
      }
    }
  }
}

The local MCP process uses your API key to communicate with Umami Cloud.

This gives clients that require a local MCP process a way to access the same Umami analytics functionality.

What Can Your AI Agent Do With Umami?

The Umami MCP server provides a broad set of read-only analytics tools.

The first tool an AI agent will typically use is list_websites. This lets it discover the websites available to your account and obtain the websiteId needed for subsequent analytics requests.

From there, your AI agent can query traffic, events, sessions, conversions, attribution, performance data, and more.

Website and Date Information

list_websites

Find the websites available to your account.

get_website_daterange

Find the earliest and latest dates for which a website has recorded data.

These tools are useful for establishing what websites are available and what historical period can be analyzed.

Website Statistics

get_website_stats

Retrieve high-level statistics including:

Pageviews
Visitors
Visits
Bounce rate
Visit duration
Previous-period comparisons

This is useful for questions that require a quick overview of website performance.

Traffic Over Time

get_website_traffic

Retrieve pageview and visit time series data.

The data can be grouped by:

Minute
Hour
Day
Month
Year

This allows an AI agent to investigate traffic patterns and changes over specific periods.

Traffic Sources and Website Metrics

get_website_metrics

Retrieve information about the performance of different parts of your website and traffic sources, including:

Top pages
Referrers
Channels
Countries
Browsers
Devices
UTM data
Events

This makes it possible to ask natural-language questions about where visitors are coming from and what they’re doing on your site.

Real-Time Visitors

get_realtime

Find visitors who are active on your website right now.

This can be useful when monitoring a launch, campaign, announcement, or sudden increase in traffic.

Events

Umami’s event data can also be queried through MCP.

Available tools include:

get_events

Retrieve individual tracked events, with pagination.

get_event_stats

Get custom event totals and compare them with a previous period.

get_event_series

View custom event counts over time, grouped by event name.

get_event_properties

Explore custom event property names and retrieve the values associated with a specific property.

This means an AI agent can go beyond basic pageviews and analyze the actions visitors take on your website.

Sessions and Visitor Journeys

MCP also provides access to session-level analytics.

get_sessions

Retrieve visitor sessions.

get_session

Retrieve an individual session, including its activity timeline and properties.

get_session_stats

Get session-level totals such as visitors, visits, pageviews, events, and countries.

You can also use run_journey to identify the most common paths visitors take through your website.

This can help an AI agent investigate how people navigate from one page to another rather than looking at individual pageviews in isolation.

Funnels and Goals

If you use funnels and goals in Umami, your AI agent can analyze them as well.

list_funnels

Find your saved funnels and their steps.

run_funnel

Run a saved funnel or create an ad-hoc funnel using page and event steps.

get_goals

Retrieve saved goals along with conversions, visitors, and conversion rates for a specified date range.

This allows you to ask questions about conversion performance using ordinary language instead of manually navigating through your analytics dashboard.

Segments and Cohorts

The MCP server also supports saved segments and cohorts.

list_segments

Retrieve your saved segments and cohorts.

You can then pass segment or cohort IDs through the appropriate filters when querying analytics.

This is useful when you want your AI agent to analyze a specific group of visitors rather than your entire audience.

Retention and Attribution

Two additional tools provide deeper analysis of visitor behavior.

run_retention

Generate a cohort retention table.

run_attribution

Analyze first-click or last-click attribution for a conversion.

Together, these tools can help answer questions about whether visitors return to your website and which traffic sources are associated with conversions.

Revenue Analytics

get_revenue

Retrieve revenue totals, time series, and breakdowns.

If your Umami setup tracks the relevant revenue information, an AI agent can use this data alongside other analytics to investigate commercial performance.

Website Performance and Core Web Vitals

MCP isn’t limited to traffic and conversion analytics.

get_performance

Provides Core Web Vitals and performance information, including:

LCP
INP
CLS
FCP
TTFB

The data includes percentiles, trends, and breakdowns.

For example, you can ask your AI agent to investigate which pages have poor LCP performance on mobile and use the returned analytics to identify where to look more closely.

Annotations

get_annotations

Retrieves dated notes associated with your analytics timeline.

Annotations can document events such as launches, campaigns, or other changes that might explain an unusual movement in traffic.

This is particularly useful when asking an AI agent to investigate why something changed.

For example, if traffic suddenly increased on a particular day, annotations can provide additional context for interpreting the change.

Example Questions to Ask Your AI Agent

Once Umami MCP is connected, you don’t need to think in terms of API calls or individual analytics endpoints.

You can simply ask questions in natural language.

Here are some examples:

Show my websites.

How many visitors did my website get last week?

What were the top 10 pages this month?

Compare traffic this month with the previous month.

Where is my traffic coming from?

What signup events occurred yesterday?

Which pricing plans did people select in the checkout event last month?

Run my checkout funnel for last month.

How are we doing against our goals this quarter?

Which pages have the worst LCP on mobile?

What happened on the day traffic spiked?

The AI agent determines which Umami tools it needs to use to answer the question.

Going Beyond Simple Analytics Questions

The real value of connecting Umami to an AI agent is that you can combine multiple analytics sources in a single investigation.

For example, instead of manually checking several dashboard reports after a traffic spike, you could ask:

What happened on the day traffic spiked?

An AI agent can investigate traffic data, identify relevant pages or referrers, examine events, and check annotations to provide a more complete picture of what changed.

Similarly, a question about conversions might involve goals, events, funnels, traffic sources, and attribution.

MCP gives the AI agent access to the underlying analytics tools needed to perform that kind of investigation.

Dates, Pagination, and Data Limits

Umami MCP uses ISO 8601 dates when working with date ranges.

Results are paginated, with a hard cap on page size.

This is important when asking questions involving large datasets. An AI agent may need to retrieve multiple pages of results when investigating detailed event or session data.

For broad questions such as monthly traffic totals, the relevant analytics tools can generally return the aggregate information needed without requiring you to manually handle pagination.

Security and Permissions

The Umami MCP integration is designed around the permissions already present in Umami Cloud.

The MCP tools are read-only.

The MCP server calls the same Cloud API used by the Umami dashboard, rather than accessing your underlying analytics data directly.

Your existing website and team permissions therefore continue to apply.

The most important security consideration on your side is your API key. Anyone who obtains the key may be able to access the Umami data available to that key, so store it securely and don’t expose it in public code, repositories, screenshots, or client-side applications.

How to Disconnect an AI Tool

Access to the Umami MCP server is tied to your API key.

If you want to disconnect an AI tool, revoke the API key associated with it.

In Umami, go to:

Settings → API keys

Delete the key you no longer want to use.

Because access is tied to the API key, revoking that key prevents the AI client from continuing to authenticate with Umami using it.

Putting It All Together

Umami MCP turns your analytics into something you can interrogate conversationally.

Once your AI client is connected, you can ask questions about traffic, pages, visitors, events, sessions, funnels, goals, attribution, revenue, retention, and website performance without manually moving between different analytics reports.

The workflow is straightforward:

Create an Umami Cloud API key.
Connect your MCP-compatible AI client to the Umami MCP endpoint.
Authenticate using your API key.
Ask your AI agent questions about your website.
Let the agent use the appropriate read-only Umami tools to investigate the data.

The result is a more natural way to work with analytics: instead of starting with a dashboard and searching for the right report, you can start with a question and let your AI agent find the relevant data.

Get Started with Managed Umami

Ready to try Umami without the DevOps hassle? UmamiEngine provides fully managed Umami analytics with all the depth described above, including funnels, retention, journeys, attribution, and revenue insights. No servers, no databases, no maintenance, just privacy-first analytics in minutes. Get started today and take control of your analytics data.

Get fully managed Umami in minutes