Matomo MCP Server (Read-Only)

A local MCP server for Claude Code, Claude Desktop and Codex. Use it to read Matomo analytics, compare traffic and conversions, and investigate visits and User ID reports.

The server only reads from Matomo: it cannot change sites, goals, segments or users.

1. Install

You need Node.js 24+ and a Matomo account with an API token and access to at least one site.

node -v
npm install -g @martin4455/matomo-mcp-ro@latest

These setup instructions require version 0.4.2+. For an unreleased checkout, use the source setup.

2. Configure

Run the configurator in your project directory:

cd "/absolute/path/to/project"
matomo-mcp configure

Enter your HTTPS Matomo URL (for example, https://matomo.example.com) and API token. Create a token under Administration → Personal → Security → Create new token; see the Matomo token guide. If your server also requires HTTP Basic Auth, enter its login and password. The configurator tests the connection before saving.

The URL, token and optional Basic Auth credentials are encrypted together and stored in macOS Keychain, Windows Credential Manager or Linux Secret Service (such as GNOME Keyring). The project's .matomo-mcp.json stores a UUID reference, not credentials. There is no additional passphrase when starting a session. Access protection comes from the OS credential store; see the encryption details and limits.

Existing entries in the old format are treated as invalid credentials. Run matomo-mcp configure again and enter the complete connection.

3. Connect your client

From the same project directory, run the command for your client.

Claude Code:

claude mcp add matomo-local -- npx -y @martin4455/matomo-mcp-ro@latest --config .

Start Claude Code from this directory so . selects your local configuration. For Windows launch problems, see launcher troubleshooting.

Codex CLI:

Replace the quoted path with the directory you configured above.

codex mcp add matomo-local -- npx -y \
  @martin4455/matomo-mcp-ro@latest --config "/absolute/path/to/project"

Claude Desktop: follow the Desktop setup.

Start or restart your client. In Claude Code or Codex CLI, use /mcp to check the server's status. The first launch may take a moment to download the package.

4. Try it

Ask your assistant:

Use matomo-local to check which Matomo sites I can access.

Then give it an analytics question:

Compare visits, traffic sources and goal conversions for site 1 in September 2026 with August 2026. Explain the largest changes and flag incomplete data.

You can also ask about a particular User ID, visit details or custom dimensions. Use the server name you registered; the generated Desktop settings use matomo.

For token changes, platform requirements, storage details, report tools and troubleshooting, see the configuration guide.

MIT license. Source | Report an issue.