Matomo Analytics

io.github.LiohtmlPublished by GitHub account Liohtmlv0.1.4Updated Oct 24, 2026

Curated read-only Matomo Analytics tools: traffic, pages, referrers, e-commerce, real-time & more.

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

A local MCP server that gives an AI assistant read-only access to Matomo Analytics reports: traffic, pages, referrers, e-commerce, goals and real-time visitors.

What you can do
List tracked sites and pull traffic summaries for a chosen period and date range, with optional segments and row limits. Break down pages, entry and exit pages, referrers and campaigns, events, goals and e-commerce revenue and products. Inspect visitor geography, devices and browsers, visit times, site search terms and page performance. Show real-time visitor counters and the live visit log, and read annotations tied to traffic changes. Call any Matomo Reporting API method through a generic escape-hatch tool for funnels, heatmaps or custom dimensions.
When to use it
Useful when you want an assistant to answer analytics questions from a Matomo instance in conversation, such as comparing traffic periods, finding top landing pages or checking live visitors, without building dashboards or queries by hand.
Requirements
Runs as a local process: a prebuilt binary, cargo install, or the Docker image. Needs MATOMO_URL pointing at the Matomo root and a MATOMO_TOKEN API token with at least view access; MATOMO_DEFAULT_SITE_ID is optional. Network access to the Matomo instance is required.
Before you install
The token is a credential: it is sent to the configured Matomo instance and should be kept out of shared config files. Tools are described as read-only, but the generic API tool can reach any Reporting API method, so review what it is asked to call. The optional HTTP mode has no built-in authentication and should stay bound to localhost or sit behind an authenticating proxy. MATOMO_INSECURE disables TLS verification.

Installation

In SourceWeft

  1. Open Matomo Analytics in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[matomo-mcp logo]

matomo-mcp

Talk to your Matomo Analytics. From Claude, Cursor, VS Code, or any MCP client.

[CI] [Crates.io] [License: MIT] [Rust] [MCP]

15 curated, read-only analytics tools + a full-API escape hatch. Single binary, instant startup, context-friendly.

Quickstart · Clients · Tools · Configuration · FAQ

text
You  ▸ How was traffic yesterday, and where did it come from?
Claude ▸ Yesterday you had 14,472 visits (11,416 unique visitors, 66% bounce rate).         Top acquisition channels:         1. Organic search — 6,120 visits (Google 92%)         2. Direct — 4,890 visits         3. AI assistants — 1,204 visits (↑ 31% vs. last week)         Want me to break down which landing pages converted best?

Every question your Matomo dashboard can answer, your AI assistant can now answer too — including follow-ups, comparisons, and "why?".

✨ Why matomo-mcp?

🎯 Curated, not generated15 hand-crafted tools modeled on real analytics questions — not 70+ auto-generated API mirrors that flood the model's context and degrade tool selection.
⚡ Instant startupNo introspection round-trips. One static binary, no Node, no Python, no runtime. Starts in milliseconds.
🔒 Safe by defaultRead-only reporting tools. Token sent via POST only (never in URLs/logs), redacted from every error. TLS verification on by default.
🧠 Context-friendlyRow limits on every report and a hard response budget with actionable guidance — one tool call can never blow up the context window.
📡 Real-time includedLive visitor counters and a visit log (matomo_realtime) — see what's happening right now.
🧰 Never a cagematomo_api reaches any Reporting API method (funnels, heatmaps, custom dimensions, …) when the curated tools don't cover it.
🔁 ResilientAutomatic retries with backoff on 429/5xx/network hiccups. Helpful, hint-annotated error messages the model can act on.

🚀 Quickstart

1. Install

Prebuilt binary (Linux, macOS, Windows) — grab it from Releases, or:

bash
# Cargocargo install matomo-mcp
# From sourcecargo install --git https://github.com/Liohtml/matomo-mcp
# Dockerdocker pull ghcr.io/liohtml/matomo-mcp

2. Get a Matomo API token

Matomo → Settings (⚙) → Personal → Security → Auth tokens → Create new token. View-only permissions are all it needs.

3. Verify the connection

bash
matomo-mcp --url https://your-matomo.example.com --token YOUR_TOKEN --check
text
✓ Connected — Matomo version 5.2.1✓ Token grants access to 3 site(s):    #1 My Shop (https://shop.example.com)    #2 Blog (https://blog.example.com)    #3 Docs (https://docs.example.com)

4. Connect your client ⬇

🔌 Connect your client

Claude Code
bash
claude mcp add matomo \  --env MATOMO_URL=https://your-matomo.example.com \  --env MATOMO_TOKEN=YOUR_TOKEN \  --env MATOMO_DEFAULT_SITE_ID=1 \  -- matomo-mcp
Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

json
{  "mcpServers": {    "matomo": {      "command": "matomo-mcp",      "env": {        "MATOMO_URL": "https://your-matomo.example.com",        "MATOMO_TOKEN": "YOUR_TOKEN",        "MATOMO_DEFAULT_SITE_ID": "1"      }    }  }}
Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

json
{  "mcpServers": {    "matomo": {      "command": "matomo-mcp",      "env": {        "MATOMO_URL": "https://your-matomo.example.com",        "MATOMO_TOKEN": "YOUR_TOKEN",        "MATOMO_DEFAULT_SITE_ID": "1"      }    }  }}
VS Code (GitHub Copilot)

.vscode/mcp.json:

json
{  "servers": {    "matomo": {      "type": "stdio",      "command": "matomo-mcp",      "env": {        "MATOMO_URL": "https://your-matomo.example.com",        "MATOMO_TOKEN": "${input:matomo-token}",        "MATOMO_DEFAULT_SITE_ID": "1"      }    }  },  "inputs": [    {      "id": "matomo-token",      "type": "promptString",      "description": "Matomo API token",      "password": true    }  ]}
Windsurf / Zed / other MCP clients

Any client that speaks MCP over stdio works with the generic shape:

json
{  "command": "matomo-mcp",  "args": [],  "env": {    "MATOMO_URL": "https://your-matomo.example.com",    "MATOMO_TOKEN": "YOUR_TOKEN",    "MATOMO_DEFAULT_SITE_ID": "1"  }}
Docker (any client)
json
{  "mcpServers": {    "matomo": {      "command": "docker",      "args": [        "run", "-i", "--rm",        "-e", "MATOMO_URL", "-e", "MATOMO_TOKEN", "-e", "MATOMO_DEFAULT_SITE_ID",        "ghcr.io/liohtml/matomo-mcp"      ],      "env": {        "MATOMO_URL": "https://your-matomo.example.com",        "MATOMO_TOKEN": "YOUR_TOKEN",        "MATOMO_DEFAULT_SITE_ID": "1"      }    }  }}
Streamable HTTP — host once, connect many clients

Run the server once (on a workstation, LAN box, or container) and point any number of MCP clients at it:

bash
matomo-mcp --url https://your-matomo.example.com --token YOUR_TOKEN --http 127.0.0.1:8080

Clients connect to http://127.0.0.1:8080/mcp with the streamable HTTP transport, e.g.:

bash
claude mcp add --transport http matomo http://127.0.0.1:8080/mcp

[!WARNING] The HTTP endpoint has no built-in authentication. Keep it bound to 127.0.0.1, or put a reverse proxy with auth (or a firewall) in front before exposing it beyond localhost.

[!TIP] Set MATOMO_DEFAULT_SITE_ID and the model never has to ask which site you mean. No token at hand? Try it against the public demo: --url https://demo.matomo.cloud --default-site-id 1 (no token needed).

🧭 Tools

ToolAnswers questions like
matomo_list_sites"Which sites do we track?"
matomo_visits_summary"How much traffic did we get last week?"
matomo_pages"What are our top pages? Where do people exit?"
matomo_referrers"Where do visitors come from? Which campaigns work? What do AI assistants send us?"
matomo_events"How often was the configurator opened?"
matomo_goals"What's our conversion rate per goal?"
matomo_ecommerce"Revenue this month? Best-selling products?"
matomo_geo"Which countries/cities do visitors come from?"
matomo_devices"Mobile vs. desktop? Which browsers?"
matomo_visit_times"When during the day/week do people visit?"
matomo_site_search"What do people search for on our site — and find nothing?"
matomo_realtime"Who's on the site right now?"
matomo_page_performance"Which pages load slowly?"
matomo_annotations"Which deploys or campaign launches line up with that traffic spike?"
matomo_apiEverything else — funnels, heatmaps, custom dimensions, any Module.action of the Reporting API

All tools accept site_id, period (day/week/month/year/range), date (today, yesterday, 2026-07-01, last30, or start,end ranges), an optional segment (e.g. deviceType==mobile;country==DE), and a row limit.

Prompts to try

  • "Compare this week's traffic with last week — what changed and why?"
  • "Top 10 landing pages by conversions this month, with bounce rates."
  • "Are we getting traffic from ChatGPT or Perplexity? Trend over 3 months."
  • "Which internal searches return no results? Suggest content we should create."
  • "Anything unusual in the visitor log right now?"

⚙️ Configuration

FlagEnvDefaultDescription
--urlMATOMO_URL—Matomo instance URL (sub-directory installs like https://example.com/matomo/ work). Without it the server still starts and tool calls return setup guidance
--tokenMATOMO_TOKEN—API token (token_auth), view access is enough
--default-site-idMATOMO_DEFAULT_SITE_ID—Site used when the model doesn't specify one
--headerMATOMO_EXTRA_HEADERS—Extra HTTP headers (Name:Value, repeatable / comma-separated) — for auth proxies, Zero-Trust, multi-tenant setups
--timeout-secsMATOMO_TIMEOUT_SECS30Per-request timeout
--max-response-charsMATOMO_MAX_RESPONSE_CHARS50000Response budget before truncation
--httpMATOMO_HTTP_BIND—Serve MCP over streamable HTTP on this address instead of stdio (endpoint: http://<addr>/mcp)
--insecureMATOMO_INSECUREfalseAccept self-signed TLS certificates (explicit opt-in)
--check——Verify URL + token + site access, then exit

🆚 How is this different from FGRibreau/mcp-matomo?

mcp-matomo (which inspired this project — thanks! 🙏) introspects your Matomo instance at startup and generates one MCP tool per API method. matomo-mcp takes the opposite approach:

matomo-mcpmcp-matomo
Tool set15 curated tools + escape hatch~70+ generated tools
Model context costSmall, stableLarge, instance-dependent
Parameter typesExact, hand-written enums/defaultsInferred from parameter names
StartupInstant (no network I/O)Introspection round-trips (or cached spec file)
TLS verificationOn by defaultDisabled for introspection
Sub-directory installs✅Path is overwritten
Response size guardRow limits + hard budget—
Retries on transient errors✅—
Real-time (Live) tools✅— (not part of report metadata)

If you want every API method as its own tool, use mcp-matomo. If you want the model to reliably pick the right tool and never flood its context, use matomo-mcp.

🩺 Troubleshooting

"site_id is required"

Either pass --default-site-id 1 (recommended) or let the model call matomo_list_sites first.

401 / "cannot be authenticated"

Run matomo-mcp --url ... --token ... --check. If it fails: regenerate the token (Settings → Personal → Security), make sure it has at least view access to the site.

404 or HTML instead of JSON

MATOMO_URL must point at the Matomo root — the folder containing index.php. For https://example.com/matomo/index.php, use https://example.com/matomo/.

Behind Cloudflare Access / OAuth2 proxy / Zero Trust?

Inject the bypass headers: --header "CF-Access-Client-Id:..." --header "CF-Access-Client-Secret:..." (or via MATOMO_EXTRA_HEADERS).

Responses feel truncated

That's the context guard doing its job. Ask for fewer rows, a shorter date range, or raise --max-response-chars.

🗺️ Roadmap

  • Streamable HTTP transport (--http, host it once, connect many clients)
  • matomo_annotations — read & correlate deploy markers with traffic
  • Multi-instance support (one server, several Matomo installations)
  • Homebrew tap & winget manifest
  • MCP registry listing (official registry via server.json, Glama)

Want one of these sooner? Open an issue — or a PR, see CONTRIBUTING.md.

🛠️ Development

bash
cargo test                                   # 37 tests, fully offline (wiremock)cargo clippy --all-targets -- -D warningscargo run -- --url https://demo.matomo.cloud --default-site-id 1 --check

Architecture and design decisions: docs/ARCHITECTURE.md.

📄 License & Credits

MIT. Not affiliated with or endorsed by Matomo — Matomo is a registered trademark of InnoCraft Ltd.

Built with rmcp, the official Rust MCP SDK. Inspired by FGRibreau/mcp-matomo.

  • MCP Registry name: mcp-name: io.github.Liohtml/matomo-mcp

If matomo-mcp saves you a dashboard visit, a ⭐ helps others find it.

Source: README.md at commit 2be7efb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.4LatestOct 15, 2026
  2. v0.1.3Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts