Integrate the Matomo MCP Server with a third-party MCP client

The Matomo MCP Server supports MCP clients beyond those covered by available integration guides. An MCP client is an external AI application or tool that connects to the MCP Server, such as OpenAI Desktop App, Codex and Claude Desktop.

Third-party clients authenticate using a Matomo API token or OAuth 2.0, send requests to Matomo and use the returned analytics data in their responses. The client must support connecting to a remote MCP server using the endpoint URL provided by Matomo.

This guide explains the general steps for connecting a compatible third-party MCP client. Interface labels, authentication options and setup requirements will vary between different MCP clients.

Before you start

Review the third-party MCP client’s security, privacy and data retention policies, then complete the following steps before connecting the client:

1. In Matomo, enable and configure the MCP Server.
2. Copy the MCP endpoint shown in Administration > Export / or Platform (On-Premise) > MCP Server.
   
3. Choose an authentication method supported by the client. The authentication method determines which Matomo data the client can access. Matomo API tokens inherit the user’s permissions, while OAuth access is limited by the approved scopes.
   • Use a Matomo API token when the client supports bearer-token authentication.
   • Use OAuth 2.0 when the client supports Matomo’s OAuth implementation and manually configured endpoints.

Connect using a Matomo API token

1. Select which Matomo user the MCP client will authenticate as. For tighter access control, create a dedicated user with only the required website permissions.
2. Log in as that user.
3. Generate and copy the Matomo API token.

Configure the MCP client with a token

1. When setting up the MCP client connection, different clients use different names for external connections. Look for MCP Servers, Connectors, Integrations, Plugins or Developer settings.
2. Create a custom MCP connection in the third-party client.
3. Paste the Matomo MCP endpoint into the Server URL, Endpoint URL, Remote MCP Server URL or equivalent field.
4. Select Bearer token authentication (or API Key if it sends the token using the Authorization: Bearer header) and enter the Matomo API token. The Matomo token inherits the permissions of the Matomo user who created it. Store the token securely and rotate it periodically.
5. Do not add the token_auth to the MCP endpoint URL.
6. If the client requires a custom HTTP header, configure:

Header name: Authorization
Header value: Bearer YOUR_TOKEN_AUTH

If the client uses another header format, review its official documentation for custom Authorization headers or bearer-token authentication. If neither option is supported, use OAuth 2.0 where compatible.

Connect using OAuth 2.0

OAuth 2.0 uses temporary access tokens instead of exposing a permanent Matomo API token.

Note: The client must support Matomo’s OAuth endpoints and manage its OAuth tokens. Clients that rely only on automatic discovery may not work in every environment. If the client cannot use manually configured OAuth endpoints, use a Matomo API token with bearer authentication.

1. Log in to Matomo as a superuser.
2. Go to Administration > Export / or Platform (On-Premise) > OAuth 2.0 to create an OAuth client for the third-party application. See how to configure OAuth 2.0 in Matomo.
3. In the Matomo OAuth settings, select the client Type specified in the MCP client’s documentation. Choose Confidential if it requires a client secret or Public if it requires only a client ID.
4. Select the Allowed grant types required by the client:
   • Enable Authorisation code when using a redirect URI.
   • Enable Refresh token if the client supports refresh tokens.
   • Enable Client credentials only when required for server-to-server authentication.
5. Under Allowed scope, select Matomo read level access for read-only analytics access.

6. A redirect URI is required for the Authorisation Code grant. It is not required for the Client Credentials grant.
   

7. Enter the exact Redirect URI supplied by the MCP client. This is found in the MCP client interface or documentation (also referred to as the callback URL), for example:
   

8. Save the OAuth client in Matomo and copy its Client ID and/or Client Secret (if you created a Confidential client). The client secret appears only when the OAuth client is saved.

Configure the MCP client with OAuth

1. Go to your third-party app to set up the MCP client connection. Different models use different names for external connections. Look for MCP Servers, Connectors, Integrations, Plugins or Developer settings.
2. Create a custom MCP connection in the third-party client.
3. Paste the Matomo MCP endpoint into the Server URL, Endpoint URL, Remote MCP Server URL or equivalent field.
4. Choose OAuth 2.0 authentication. Enter the Client ID and, for a Confidential client, enter the Client Secret (see step 8 above).

5. Some MCP clients discover the OAuth endpoints automatically. Enter the endpoint URL if the client requests them and replace YOUR_MATOMO_URL with your Matomo instance URL:
   

   • Authorisation endpoint:
     https://YOUR_MATOMO_URL/index.php?module=OAuth2&action=authorize
   • Token endpoint:
     https://YOUR_MATOMO_URL/index.php?module=OAuth2&action=token

6. The token endpoint handles authorisation code exchanges, access-token requests, refresh tokens and Client Credentials authentication. See the Matomo OAuth 2.0 developer documentation.

After connecting the client, test it with a read-only request. Confirm that it can access only the intended websites and reports. If the connection fails, review the endpoint, authentication settings and client compatibility requirements.