Matomo Analytics

What Matomo Analytics MCP server does

Matomo Analytics MCP server connects an MCP-compatible AI client to a Matomo instance and turns reporting queries into structured tool calls. Its primary interface is a set of 15 read-only tools covering common analytics questions, including traffic summaries, top pages, referrers, events, goals, e-commerce, geography, devices, visit timing, internal search, real-time visitors, page performance, annotations, and site listings.

The server is intended for analysis rather than administration. It can retrieve reporting data but does not provide tools for changing Matomo configuration or writing analytics data. A separate matomo_api tool provides access to other Matomo Reporting API methods, including areas such as funnels, heatmaps, and custom dimensions.

How it works

The binary communicates with MCP clients over stdio by default. It can also expose a streamable HTTP endpoint, allowing multiple clients to connect to one running instance. The HTTP endpoint does not include built-in authentication, so the README recommends keeping it on localhost or placing authentication, a firewall, or a reverse proxy in front of it before remote exposure.

Tool calls can specify a Matomo site, reporting period, date or date range, segment, and row limit. Supported periods include day, week, month, year, and range. Date examples include relative values such as today, yesterday, and last30, as well as explicit dates and start/end ranges.

Responses are constrained by row limits and a response budget. The server also retries selected rate-limit, server, and network failures with backoff, while redacting the API token from errors and sending the token through POST requests rather than URLs.

Setup and configuration

Install the binary from the project’s releases, with Cargo, from the Git repository, or through the published Docker image. A Cargo installation uses the matomo-mcp package and produces the matomo-mcp executable.

Provide the Matomo instance URL through MATOMO_URL or the --url flag, and provide a Matomo authentication token through MATOMO_TOKEN or --token. The token should have view permissions. MATOMO_DEFAULT_SITE_ID can select a default site so the model does not need to ask for one on every request.

Before connecting a client, the --check option verifies the Matomo connection and reports the Matomo version and sites available to the token. The README also documents a public Matomo demo that can be used without a token.

Tools and capabilities

• List tracked Matomo sites.
• Summarize visits and visitor traffic.
• Inspect pages, exits, referrers, campaigns, events, goals, and e-commerce results.
• Analyze visitor geography, devices, visit times, and internal site searches.
• View current visitor activity through real-time reporting.
• Check page performance and relate traffic changes to annotations.
• Call other Matomo Reporting API methods through matomo_api.

Limitations and notes

Matomo Analytics MCP server requires access to a Matomo instance for normal use and relies on a Matomo API token unless connecting to the documented public demo. The available reporting data depends on the token’s permissions and the selected site. The built-in HTTP mode has no authentication of its own, so exposing it outside localhost requires additional protection. The curated tools are read-only; broader API access does not imply that the server provides Matomo administration tools.