Openmost Matomo MCP

Talk to your Matomo analytics. Openmost Matomo MCP connects Claude (or any MCP-compatible AI assistant) to your Matomo instance, so you can explore your data, build reports and get insights by simply asking questions.

"How many visits did my site get last week compared to the week before?"
"Which pages have the highest bounce rate this month?"
"Show me the top referrers for site #3 yesterday."

👉 Product page: openmost.com/matomo/extensions/matomo-mcp-client

✨ What is Openmost Matomo MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants use external tools and data sources. Openmost Matomo MCP is a hosted MCP service, built by Openmost, that gives your assistant access to your Matomo analytics data:

• 📊 Analyze your traffic: visits, pages, referrers, campaigns, goals, conversions…
• 🌐 Manage your sites: list and explore the websites tracked in your Matomo.
• 🔔 Work with alerts and reports: access your Matomo data without leaving the conversation.
• 💬 Built-in prompts: ready-made analysis templates to get useful insights quickly.
• 🔄 Always up to date: tools and prompts are provided by the Openmost server, so new features become available without updating anything on your side.

It works with Matomo On-Premise and Matomo Cloud, and you keep using your own Matomo instance and permissions.

Architecture

The service is made of two parts:

1. The Openmost Matomo MCP server (https://matomo-mcp.openmost.com), hosted by Openmost. It exposes the Matomo tools and prompts, and queries your Matomo instance through its API.
2. The Matomo MCP client (this repository), a lightweight Node.js program that runs on your machine. Claude Desktop starts it locally and it relays the requests to the Openmost server.

Claude Desktop  ⇄  Matomo MCP client (local)  ⇄  Openmost Matomo MCP server  ⇄  Your Matomo

ℹ️ Your Matomo URL and API token are sent to the Openmost MCP server with each request so that it can query Matomo for you. To limit what the assistant can access, use the token of a Matomo user with view access only.

✅ Requirements

• Node.js 18 or later
• Claude Desktop (or another MCP-compatible client)
• A Matomo instance (On-Premise or Cloud) and a Matomo API token
• An Openmost MCP token, available on demand via our contact form

Getting your Matomo API token

In Matomo, go to Administration (⚙️) → Personal → Security → Auth tokens, then click Create new token.

🚀 Installation

git clone https://github.com/openmost/matomo-mcp-client
cd matomo-mcp-client
npm install

Note the absolute path to matomo-mcp-client.js; you will need it in the next step:

pwd
# e.g. /Users/you/matomo-mcp-client  →  /Users/you/matomo-mcp-client/matomo-mcp-client.js

🔧 Configuration in Claude Desktop

1. Open the configuration file

In Claude Desktop, go to Settings → Developer → Edit Config. You can also open the file directly (create it if it does not exist):

2. Add the MCP server

{
  "mcpServers": {
    "openmost-matomo-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/matomo-mcp-client/matomo-mcp-client.js",
        "--matomo-host=https://matomo.example.com",
        "--matomo-token=YOUR_MATOMO_TOKEN",
        "--openmost-token=YOUR_OPENMOST_TOKEN"
      ]
    }
  }
}

If the file already contains other servers, add the "openmost-matomo-mcp" entry inside the existing "mcpServers" object.

On Windows, escape the backslashes in the path: "C:\\Users\\you\\matomo-mcp-client\\matomo-mcp-client.js".

{
  "mcpServers": {
    "openmost-matomo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/matomo-mcp-client/matomo-mcp-client.js"],
      "env": {
        "MATOMO_HOST": "https://matomo.example.com",
        "MATOMO_TOKEN_AUTH": "YOUR_MATOMO_TOKEN",
        "OPENMOST_MCP_TOKEN": "YOUR_OPENMOST_TOKEN"
      }
    }
  }
}

3. Restart Claude Desktop

Quit Claude Desktop completely (not just the window) and reopen it.

🎉 Usage

After the restart, open a new conversation. openmost-matomo-mcp should appear in the tools menu (🔨 / connectors icon) of the message box. Then just ask your question:

• "List all my Matomo sites."
• "Give me a summary of last month's traffic for site 1."
• "Which marketing channels brought the most conversions this quarter?"

Claude will ask for your permission the first time it uses a Matomo tool.

⚙️ Options

Every option can be set either as a command-line argument or as an environment variable. Command-line arguments take precedence.

Built-in behavior:

• Cache: the tools and prompts lists are cached for 5 minutes.
• Retries: failed requests are retried with exponential backoff. Authentication errors (401/403) are not retried.
• Startup check: the client tests that the server is reachable at startup, unless NODE_ENV=production.

🩺 Troubleshooting

Check your configuration from a terminal. If something is wrong, the client prints an explicit error:

node matomo-mcp-client.js \
  --matomo-host=https://matomo.example.com \
  --matomo-token=YOUR_MATOMO_TOKEN \
  --openmost-token=YOUR_OPENMOST_TOKEN

If the configuration is valid, the client starts and waits for an MCP connection (stop it with Ctrl+C).

The server does not appear in Claude Desktop

• Check that claude_desktop_config.json is valid JSON (no trailing commas).
• Check that the path to matomo-mcp-client.js is absolute and correct.
• Make sure you fully quit and restarted Claude Desktop.

spawn node ENOENT or "server disconnected"
Claude Desktop cannot find Node.js. This often happens with nvm, asdf or Homebrew. Run which node (macOS/Linux) or where node (Windows) and use the full path as "command", e.g. "/Users/you/.nvm/versions/node/v20.11.0/bin/node".

Authentication errors (401 / 403 / Invalid token)
Check your Openmost token, and check that your Matomo token is valid and has access to the requested sites.

Logs
The client writes its logs to stderr. Claude Desktop saves them in:

• macOS: ~/Library/Logs/Claude/mcp-server-openmost-matomo-mcp.log
• Windows: %APPDATA%\Claude\logs\mcp-server-openmost-matomo-mcp.log

📖 Resources

• Openmost Matomo MCP: product page
• Matomo Analytics
• Claude Desktop
• Model Context Protocol