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

This guide explains how to connect Matomo to the OpenAI desktop app and Codex CLI. To use the ChatGPT web version, see the guide on integrating with ChatGPT Web.

  1. Ensure the Matomo MCP server is enabled.
  2. For Matomo On-Premise, install and activate the MCP server plugin.
  3. You will need access to the OpenAI desktop app or Codex CLI.
  4. Note your Matomo MCP endpoint URL found in the MCP settings.
  5. Generate a Matomo API token; or
  6. You can use OAuth 2.0 to create access tokens. For Matomo On-Premise, this requires installing and activating the OAuth 2.0 plugin.

Integrate with OpenAI 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.
    openai desktop
  2. Select Codex and 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: Integrate the Matomo MCP Server with a third-party MCP client