How to configure the Matomo MCP Server

On-Premise

An MCP (Model Context Protocol) is an interface that provides a structured way for AI tools to retrieve information from external data sources. These tools use large language models (LLMs) and allow users to interact with connected data sources using natural-language questions rather than manual queries or reports.

This guide explains how the MCP works in Matomo, outlines key security and privacy considerations, and describes how to install the MCP Server plugin.

Once the MCP server plugin is installed, follow the relevant integration guide to connect the Matomo MCP Server with:

What is the Matomo MCP Server?

The MCP Server enables Matomo customers to use their OpenAI Codex and Claude accounts to query analytics data from their Matomo instance. When configured, the MCP exposes a secure, structured API layer that allows the authorised AI tools to access and analyse Matomo data and generate responses based on user queries (see examples).

This enables AI assistants and agents to retrieve website analytics from Matomo instances and summarise traffic trends, campaigns, and user behaviour.

How the MCP Server works

The Matomo MCP Server acts as a data mediation layer between an AI tool and your Matomo analytics data. Specifically:

  • It accepts structured requests (via the MCP);
  • It forwards these requests to the Matomo Analytics API;
  • It returns the requested data in a structured format.

The MCP Server does not:

  • generate content, predictions, or recommendations;
  • analyse or interpret data;
  • use machine learning or AI models;
  • get trained on your analytics data and has no inference capability.

All interpretation, reasoning, and output generation is performed exclusively by the external AI tool (LLM). This distinction is important from both a security and regulatory perspective:

  • The AI model (for example OpenAI, Anthropic, Microsoft) is the component that processes and interprets the data.
  • The MCP Server functions similarly to an API gateway or protocol adapter.

Matomo cannot guarantee the accuracy, reliability, or behaviour of third-party AI systems connected through the MCP.

Install the Matomo MCP Server plugin

Before enabling the MCP, review the Security considerations and Privacy and regulatory sections. The MCP allows external AI systems to access analytics data from your Matomo instance. You must ensure that appropriate authentication, data access controls, and privacy safeguards are in place before allowing an AI tool to query your analytics data.

If an MCP server is configured permanently (default configuration) it will always be available, even when you do not intend to use it for tasks such as coding.

Individual apps (Codex, Claude, Mac Codex app) might support options for non-permanent MCP configurations or allow deactivating MCPs on a per-need basis.

  1. In Matomo On-Premise, go to Administration matomo admin gear icon > Platform > Marketplace.
  2. Locate and install the MCP Server plugin.
  3. When installation completes, click Activate Plugin.
  4. To configure the MCP Server settings in Administration, go to System > General settings > MCP Server.
  5. Select the option Enable MCP Server (Model Context Protocol).
  6. Click Save.
  7. Copy the MCP server endpoint URL shown in the info box next to the setting.
    mcp server settings in matomo

Data access authentication

Access to the Matomo MCP server requires authentication using either a valid Matomo API token or OAuth 2.0. Authentication verifies the identity of the client and controls what data can be accessed:

  • API tokens inherit the permissions of the Matomo user who created them.
  • OAuth 2.0 enforces permissions based on the scopes granted to the OAuth client. OAuth 2.0 is supported, but not all specification features required by some clients are currently implemented.

The MCP endpoint can be used by different AI tools, but each request must be authorised. This ensures that only authenticated tools can access analytics data within the permitted scope.

Limitations when using OAuth 2.0 with the MCP plugin:

  1. Access tokens have a limited lifetime (3600 seconds by default as configured in the OAuth 2.0 client).
  2. Token refresh must currently be handled manually.
  3. The MCP plugin does not manage OAuth workflows, such as automatically fetching or refreshing tokens.
  4. OAuth 2.0 support depends on the capabilities of the MCP client:
    • Clients that allow manual configuration of token and refresh endpoints can work with OAuth 2.0.
    • Clients that require fully specification-compliant OAuth endpoints (for example, /.well-known/... URLs) may not work, as these are not fully supported in all Matomo environments.

OAuth 2.0 is best suited for clients that support manual configuration of OAuth endpoints.

Generate a Matomo API token

  1. To generate an API token in Matomo, go to Administration matomo admin gear icon > Personal > Security > Auth Tokens.
  2. Create a new authentication token.
  3. Copy the generated token.
  4. Configure the AI tool to use the MCP endpoint and token.

Setup an OAuth client

Use OAuth 2.0 to control access using defined scopes instead of user-level permissions. Read the guide on setting up OAuth 2.0 authentication in Matomo.

Note: Any tool using the token can access permitted data when querying the MCP server. The token must be stored securely and rotated periodically.

Next steps

To continue, follow the relevant integration guide to connect the Matomo MCP Server with: OpenAI Codex, ChatGPT, and Claude.

Ways to use the Matomo MCP

With the MCP, you can analyse your Matomo analytics data with questions instead of manually navigating reports or constructing complex queries. This can help teams quickly investigate trends, interpret reports, and explore patterns in website or product performance.

Analytics exploration

Discover traffic patterns, campaign performance, and visitor behaviour to identify trends and compare performance across time periods.

  • Which site had the most traffic last month?
  • Which landing pages had the most traffic yesterday on site ID 1?
  • Which campaign drove the highest conversion rate last year?

Report interpretation

Interpret analytics reports by summarising key metrics and identifying changes without manually reviewing multiple tables and charts.

  • Explain the change in visits this week compared with last week.
  • Summarise our top traffic sources this quarter.
  • What were the main changes in campaign performance this month?

Data analysis assistance

Review patterns across segments, locations, devices, or other dimensions in your analytics data.

  • Which segments show the highest conversion rates?
  • Which countries generated the newest visitors?
  • Which device types have the lowest bounce rate?

Technical assistance for analytics teams

The Matomo MCP also supports developers, analysts, and technical teams who need to investigate analytics data, monitor performance or verify that tracking works correctly.

  • Which pages have the slowest average page load time today?
  • Have any pages stopped sending tracking data?
  • Are mobile users experiencing slower page load times than desktop users?