DEEN
Book an intro call

Set up and run

Matomo API, MCP and OAuth: giving tools and AI assistants data safely

Every report in Matomo is also available as data, for BI tools, your own applications and since 2026 also for AI assistants through an official MCP server. Here is how these ways work, how to keep access as narrow as possible with tokens and OAuth, and what to settle before an AI assistant sees your numbers.

By Peter Boehlke

Updated: 8 min read

What Matomo shows in reports, it also delivers as data: for a dashboard in a BI tool, for your own application or for an AI assistant that answers questions about your numbers. The access always follows the same idea: a tool identifies itself to Matomo and gets exactly the rights behind it. How narrow those rights are is up to you.

The Reporting API: every report as data

A request to the Reporting API names the method, i.e. the report, the website, the period and the format, such as JSON, CSV, TSV or XML. Segments can be passed along, and a bulk request bundles several queries. By default, Matomo returns 100 rows per report; if you want all of them, say so explicitly.

For Matomo to know who is asking, the request needs a token. It is as secret as a password and does not belong in the address, where it ends up in log files and browser history. Since Matomo 5.4, Matomo accepts it in the request header as Authorization: Bearer, otherwise in the body of a POST request. Since Matomo 5, new tokens are by default only valid through these secure ways.

Matomo itself names one exception: tools that send their requests via GET, such as the Looker Studio connector or Matomo for WordPress, need a token without this restriction.

Tokens: one per tool

You create tokens in Matomo under Administration > Personal > Security, with a description, optionally for secure requests only, and with an expiry date. Matomo suggests 180 days and sends a reminder 30 days before expiry. A token is shown only once; it belongs in a password manager.

  • Matomo 6: tokens with their own maximum level. When creating a token, you choose the highest rights it may use: view, write, admin or super user, never more than the user has. A dashboard token can then only view, even if its user may do more. Existing tokens keep their user’s rights after the update.
  • Matomo 5 and older: a token has the rights of the user who creates it. For a tool that should only view, create a separate user with view rights.
  • Tokens outlive passwords and sign-in. A new password does not revoke existing tokens, and according to Matomo, users deactivated via LDAP or SAML keep their tokens. When someone leaves, the tokens have to be deleted explicitly.
  • Embedded reports require access that can only view: in Matomo 5 the token of a user with view rights only, in Matomo 6 also a token with the maximum level view. A token for secure requests only does not work for this, because the address of an embedded widget contains the token.
Each tool with its own access: the BI tool with a token that can only view, the AI assistant via OAuth with a short lifetime. Matomo checks with every request which rights are behind it.

OAuth 2.0: access without a fixed token

With Matomo’s free OAuth 2.0 plugin, already included in Matomo Cloud, tools get short-lived access instead of a permanent token. A super user creates a client for this under Administration > Platform > OAuth 2.0 and sets the highest rights it may get.

  • Rights as a scope: view, write, admin or super user. The client’s scope is the upper limit, and the super user level is not allowed by default.
  • Short lifetimes: an access token is valid for one hour by default, a refresh token for 30 days. Matomo recommends keeping access short, for example ten minutes.
  • For applications and services: with the user signing in through a consent screen, or as a service without a user.

The MCP server: Matomo in the AI assistant

Since May 2026, Matomo has had an official MCP server. Through this protocol, an AI assistant such as Claude, ChatGPT or Microsoft Copilot Studio queries Matomo directly and answers questions about your numbers. The MCP Server plugin is free for Matomo On-Premise, included in Matomo Cloud and switched off at first in both cases.

  • What the assistant may do: by default only view: websites, reports, goals, segments and dimensions. A super user enables direct access to further API methods separately, read-only, for individual kinds of changes or fully.
  • Who may use it: a maximum level blocks users whose rights are above it. Matomo recommends a separate user or token just for MCP access.
  • How it signs in: via OAuth where the assistant supports it, otherwise with a token in the request header, never in the address. According to Matomo, Claude Desktop only connects via OAuth.
  • Who does the thinking: the MCP server only delivers data; it is interpreted by the provider’s language model. Matomo advises checking important numbers in Matomo. And even read requests can make the server recalculate reports.
How an AI assistant queries Matomo: through the MCP server with its own rights, view-only by default. The provider's language model interprets the answer, and whatever it queries goes to that provider.

One security question is new: content from tracking, such as page titles, addresses, campaign values or search terms, can be influenced by any visitor. Matomo warns that instructions to the assistant can be smuggled in this way. For an AI assistant, analytics data is therefore untrusted input, and it should only carry out changes after asking.

Privacy: what goes to the AI provider

Whatever the assistant queries goes to its provider. In its notes on the MCP server, Matomo lists the points to settle beforehand:

  • You remain responsible; the AI provider becomes a recipient of the data. Check the contract, data processing and whether the provider uses the data for training.
  • Personal data: if Matomo collects full IP addresses, User IDs or addresses with personal details, the assistant can access them, including the visits log. Matomo then advises a data protection impact assessment and working with aggregated reports.
  • Transparency: AI providers belong in the privacy policy, the consent tool and the records of processing activities; transfers outside the EEA need checking.
  • No free versions: Matomo advises never sharing such data with public or free versions of AI tools.

Which settings in Matomo matter for this is covered in Matomo and privacy. The legal assessment stays with your legal advisers.

BI, exports and the AI reports in Matomo

  • Looker Studio: Matomo offers a free connector, for Matomo Cloud, On-Premise and Matomo for WordPress.
  • Power BI: there is no dedicated connector. The way goes through the Reporting API or, with Matomo On-Premise, through read access to the database.
  • Raw data in a data warehouse: Matomo Cloud has a paid connector for this; On-Premise, you access the database directly.
  • Reports by email: regularly as HTML, PDF or CSV, more in Email reports.

Not to be confused with the MCP server are the AI reports in Matomo itself: over the course of Matomo 5, reports on visits via AI assistants, on AI agents and on requests from AI chatbots were added, grouped under AI Insights since version 5.12. They count how AI uses your website; the MCP server lets an AI read your numbers.

How access stays under control

  • One access per tool Its own token or OAuth client, revocable individually.
  • View only With a maximum level, expiry date and short OAuth lifetimes.
  • Token in the request header Never in the address, never in chat or code.
  • AI connected deliberately Rights per use case, privacy policy checked.

Typical pitfalls

  • The super user token for everything One leak opens the whole instance.
  • Tokens without expiry After two years nobody knows who still uses them.
  • Leavers without clean-up Deactivated users keep their tokens.
  • Visits log for the assistant Individual visits go to the AI provider.

Sources

As of 13 November 2026, Matomo 5.14 and 6.0.0-rc1

FAQ

Frequently asked questions

How do I pass the token safely?

In the request header as Authorization: Bearer, which Matomo accepts since version 5.4, or in the body of a POST request. Not in the address: there it ends up in log files and browser history. Since version 5, Matomo by default only accepts new tokens this secure way.

Do I need Matomo 6 for tokens with their own permissions?

For tokens with their own maximum level, yes. In Matomo 5, a token has its user's rights. There, a separate user who may only view helps, and that user's token goes to the tool.

Does the MCP server cost anything?

No. The MCP Server plugin is free for Matomo On-Premise and included in Matomo Cloud. In both cases it is off at first and has to be switched on by a super user. Costs arise with the provider of the AI assistant.

May an AI assistant see visitor data?

Technically, it sees what the user or token may see, including the visits log if those rights exist. Matomo advises working with aggregated reports instead of individual visits, and the AI provider becomes a recipient of the data. The legal assessment stays with your legal advisers.

Questions about your setup?

In an intro call we'll look at your situation together.

Book an intro call

Newsletter

Matomo know-how, once a month.

Practical tips on tracking, privacy settings and performance, plus notes on important Matomo updates. No spam, unsubscribe any time.