Integrate the Matomo MCP Server with OpenAI Desktop App and Codex CLI

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

Before you begin, make sure you have the following:

  • The MCP Server is included with Matomo Cloud and must be manually enabled before use.
  • For Matomo On-Premise, first install and activate the MCP Server plugin and then enable the MCP in Matomo.
  • You will need access to OpenAI’s ChatGPT desktop app or Codex CLI.
  • Note your Matomo MCP endpoint URL found in the MCP settings.
  • Generate a Matomo API token. You can also use OAuth 2.0 to create access tokens.

This guide explains how to connect the Matomo MCP Server using the ChatGPT desktop app (previously Codex) or Codex CLI.

Integrate with ChatGPT desktop app

Connect the desktop app to the Matomo MCP Server by adding the server details to its config.toml configuration file.

  1. Open the desktop app and go to Settings > Configuration.
  2. Click Open config.toml. If the file does not exist, create it and save it in the required folder.
  3. You can use either the user-level configuration file at ~/.codex/config.toml or a project-level configuration file at .codex/config.toml.
  4. Add the following configuration and replace YOUR_MCP_URL with your Matomo MCP endpoint, and YOUR_API_TOKEN with your Matomo API token. 
[mcp_servers.analytics]
url = "YOUR MCP URL"
http_headers = { "Authorization" = "Bearer YOUR_API_TOKEN" }

The desktop app must be restarted so the new MCP configuration is loaded. After the restart, open a session and ask a question about your Matomo analytics data.

If the MCP server is configured correctly, the desktop app should be able to access the available analytics tools through the Matomo MCP.

Integrate with OpenAI Codex CLI

Codex CLI lets you work with Codex directly from your terminal. It uses the Codex configuration file to store MCP Server settings.

  1. Use a terminal or command-line application and start Codex CLI by running: codex
  2. Open the Codex configuration file at ~/.codex/config.toml. If the file does not exist, create it.
  3. Add the following configuration and replace YOUR_MCP_URL with your Matomo MCP endpoint, and YOUR_API_TOKEN with your Matomo API token. 
[mcp_servers.analytics]
url = "YOUR MCP URL"
http_headers = { "Authorization" = "Bearer YOUR_API_TOKEN" }

After updating the configuration file, restart the Codex CLI so the changes take effect.

To temporarily disable the MCP server without removing the configuration, add the following setting to the MCP server configuration: enabled = false.

Previous FAQ: How to configure the Matomo MCP Server