Matomo MCP — read-only analytics with local configuration

A local Node.js MCP server for Matomo Reporting API. Supports optional HTTP Basic Auth, project-local credentials, User ID reports, visit details and bounded report batches. No Matomo MCP plugin, reverse proxy, Python, keyring or listening port is required. Licensed under MIT. Version 0.3.0; Node.js 24 or later.

Install and configure

From the project where analytics will be used:

npx -y @martin4455/matomo-mcp-ro@0.3.0 configure
npx -y @martin4455/matomo-mcp-ro@0.3.0 check

Alternatively, install from source:

git clone https://github.com/luskan/matomo-mcp-ro.git
cd matomo-mcp-ro
npm ci --ignore-scripts

Then configure from the project where analytics will be used:

node "/absolute/path/to/matomo-mcp-ro/cli.mjs" configure
node "/absolute/path/to/matomo-mcp-ro/cli.mjs" check

Use npm.cmd/npx.cmd in PowerShell if script execution policy blocks .ps1. Configuration runs in your own terminal: enter the HTTPS Matomo URL, choose whether Basic Auth is required, and enter the API token and optional username/password. Credential input is hidden. Configuration is saved only after a successful read-only site-list request. Existing configurations from 0.2.1 remain valid. Enter retains saved credentials; changing the URL requires new credentials.

The file .matomo-mcp.json lives in the exact current directory, or at an explicit --config /project/.matomo-mcp.json path. No home/parent/environment fallback is used. It is plaintext protected by mode 0600 on Unix or a private Windows ACL. The same OS account can read it. Keep it out of archives and version control; configure adds Git/search exclusions. Never paste credentials into AI chats, CLI arguments, URLs or MCP client settings. status and check do not print them.

Related MCP server: Matomo MCP Server

Connect a client

Use client-config codex, client-config claude-code or client-config claude-desktop to print settings with absolute paths and no secrets. For desktop clients install to a stable local path and launch Node directly, rather than using a shell or an ephemeral npx cache:

npm install --prefix .mcp/matomo --ignore-scripts @martin4455/matomo-mcp-ro@0.3.0
node .mcp/matomo/node_modules/@martin4455/matomo-mcp-ro/cli.mjs client-config codex

Exclude .mcp/matomo/ from version control. This project-local installation needs no sudo. A supplied npm tarball can be used instead by replacing the package name with its local path.

• Codex CLI/Desktop: merge generated TOML into the trusted project's .codex/config.toml for project scope.

• Claude Code: register from that project with claude mcp add --scope local matomo -- node /absolute/path/cli.mjs serve --config /project/.matomo-mcp.json, quoting paths as required by your shell.

• Claude Desktop chat: merge generated JSON into claude_desktop_config.json. This is application scope; selecting a credential file does not create project isolation for ordinary chats.

With no command the CLI starts serve. Stdout is reserved for MCP messages. The process exits when the client closes stdin. Serving does not spawn shell helpers. Windows configuration and permission checks use hidden system utilities.

Tools

Example tool arguments (synthetic identifiers):

{
  "method": "UserId.getUsers",
  "idSite": 1,
  "period": "day",
  "date": "2026-09-01,2026-09-10",
  "segment": "dimension2==trial",
  "filter_limit": 1000,
  "filter_offset": 0
}

Confirm the actual dimension ID/value using metadata before querying. A daily series has one pagination entry per date. period=range instead returns the aggregate for the window. All dates are explicit YYYY-MM-DD values; metrics are requested as numbers (format_metrics=0).

{
  "idSite": 1,
  "period": "day",
  "date": "2026-09-10",
  "segment": "userId==example-user",
  "includeActions": true,
  "filter_limit": 20,
  "filter_offset": 0
}

Visits support at most 100 rows per page and filter_sort_order, not arbitrary sort columns. includeActions=false reduces payload. Dedupe visits by site and visit ID when collecting pages. A full page means another page may exist; inspect pagination.mayHaveMore/nextOffset. Choose closed dates where possible.

Batch takes { "requests": [REPORT_ARGUMENTS, ...], "concurrency": 1 }. Every request is validated before any network access. Results preserve request indexes; errors never become zero counts. Batch response budgets are 2 MiB per result and 8 MiB total; fetch oversized results individually with a smaller page size.

Read-only boundaries and completeness

Write methods, arbitrary API URLs, API.getBulkRequest, credential overrides and unlisted parameters are blocked before network requests. Redirects are rejected; TLS validation stays enabled. API credentials are sent as a POST body token and optional Basic Authorization header. Boolean API flags use PHP-safe 0/1 values. Requests have a 60-second timeout and 10 MiB response limit. Report page limit is 1000. Cancellation stops queued batch work.

Metadata does not automatically allow new executable methods. The server does not create saved segments, configure archiving, or change retention. Reading a report can trigger Matomo's normal archive/cache generation.

Responses preserve method, parameters, data and add fetchedAt, pagination and completeness. Others summary rows and unfetched subtables produce warnings. Finishing pagination does not prove complete telemetry: archive row limits can remove identities, raw data can expire, and tracking can be absent. Visitor-log access may also be disabled. Action lists are server-returned, not guaranteed complete. Visit-scoped dimensions do not establish a state for every individual historical action in that visit.

Use from a local Node script

The generic client export uses the same MCP transport and policy as an AI client. It never reads the credential file itself:

import { connectMatomo } from '@martin4455/matomo-mcp-ro/client';
const client = await connectMatomo({ configPath: '/project/.matomo-mcp.json' });
try {
  const sites = await client.call('matomo_list_sites', {});
  console.log(sites.data.map(site => site.name));
} finally {
  await client.close();
}

Domain identity conversions, license/business rules, input lists, caching and analysis outputs belong in separate private project skills/scripts. They are not part of this public package. No persistent job service or output-file tool is exposed over MCP.

Development

npm ci --ignore-scripts
npm test
npm run release:check
npm pack --ignore-scripts

Tests use synthetic credentials and mocked HTTP with real MCP transports. CI runs on Windows, Ubuntu and macOS. release:check verifies an explicit source and npm file list. Keep this list current when adding code; the npm package contains runtime files, README and LICENSE, not tests or private data.

• Matomo Reporting API

• Matomo API tokens

• Codex MCP

• Claude Code MCP

• MIT license