Integrate the Matomo MCP Server with Claude Desktop

Cloud On-Premise
Before integrating the MCP Server with OpenAI Codex, 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.

Before you start

  1. The MCP Server is included with Matomo Cloud. For Matomo On-Premise, you will need to first install and activate the MCP Server plugin.
  2. In both Matomo environments, the MCP will need to be manually enabled in Matomo before use. Refer to the guide on configuring the MCP Server.
  3. Ensure you have access to Claude Desktop.
  4. Generate an API auth token in Matomo. Keep this on hand as you will need it during the setup process to authenticate the connector.
  5. When generating the auth token, the option, Only allow secure requests can be disabled (unticked).
    generate auth token

Add the Matomo MCP custom connector in Claude Desktop

  1. In Claude Desktop, go to Chat > Customize > Connectors.
  2. Click the + plus icon and select Add custom connector.
  3. Expand the Context menu and select Connectors.
  4. Click Add Connector.
    add custom connector in claude
  5. Enter a unique name for the connector.
  6. Copy the MCP Server URL found in Matomo Administration admin gear icon > Export > MCP Server. When the MCP is enabled, the endpoint for MCP is displayed.

  7. In Claude Desktop, paste the MCP Server URL in the Remote MCP server field and append the auth token to the URL with &token_auth=YOUR_TOKEN.
    append auth token

  8. Click Add to authenticate.

  9. When the connection is verified, set the Tool permissions to control access to Matomo tools.

Use the Matomo MCP connector in Claude chat

When the Matomo MCP connector is successfully setup, it will appear under Connectors in Claude Desktop. You can now query your Matomo data using Claude’s chat feature as long as the Matomo MCP connector remains connected.

mcp claude desktop

Get started with example prompts that help you analyse data through the Matomo MCP. To connect the MCP with Claude Code, refer to the separate integration guide.

Troubleshooting MCP Connections

If you get the error, Couldn’t connect to the server. Check the URL points to a valid MCP server, check the following:

  • The MCP Server is enabled in Matomo’s MCP Server settings.
  • The MCP Server URL is copied exactly as shown in the Matomo settings.
  • The Matomo user associated with the API token has access to the site you want to analyse.
  • The API token was generated from the same Matomo instance and it is a valid, active token.
  • The user does not exceed any configured Maximum allowed MCP privilege level restrictions.
  • Delete and recreate the connector.
  • Generate a new API token and test again.

Test with a dedicated MCP user

For troubleshooting and security, create a dedicated Matomo user account for MCP access. The user needs site permissions and generates a new token for the MCP connector. This isolates permission and authentication issues while limiting access to analytics data.

Explore more Matomo MCP Server integration guides.

Previous FAQ: Integrate the Matomo MCP Server with Claude Code