Matomo Analytics

matomo-mcp

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

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

Quickstart · Clients · Tools · Configuration · FAQ

---

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 generated	15 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 startup	No introspection round-trips. One static binary, no Node, no Python, no runtime. Starts in milliseconds.
🔒 Safe by default	Read-only reporting tools. Token sent via POST only (never in URLs/logs), redacted from every error. TLS verification on by default.
🧠 Context-friendly	Row limits on every report and a hard response budget with actionable guidance — one tool call can never blow up the context window.
📡 Real-time included	Live visitor counters and a visit log (matomo_realtime) — see what's happening right now.
🧰 Never a cage	matomo_api reaches any Reporting API method (funnels, heatmaps, custom dimensions, …) when the curated tools don't cover it.
🔁 Resilient	Automatic 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:

# Cargo
cargo install matomo-mcp

# From source
cargo install --git https://github.com/Liohtml/matomo-mcp

# Docker
docker 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

matomo-mcp --url https://your-matomo.example.com --token YOUR_TOKEN --check

✓ 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 mcp add matomo \
  --env MATOMO_URL=https://your-matomo.example.com \
  --env MATOMO_TOKEN=YOUR_TOKEN \
  --env MATOMO_DEFAULT_SITE_ID=1 \
  -- matomo-mcp

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

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

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

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

.vscode/mcp.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
    }
  ]
}

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

{
  "command": "matomo-mcp",
  "args": [],
  "env": {
    "MATOMO_URL": "https://your-matomo.example.com",
    "MATOMO_TOKEN": "YOUR_TOKEN",
    "MATOMO_DEFAULT_SITE_ID": "1"
  }
}

{
  "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"
      }
    }
  }
}

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

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.:

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

Tool	Answers 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_api	Everything 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

Flag	Env	Default	Description
--url	MATOMO_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
--token	MATOMO_TOKEN	—	API token (token_auth), view access is enough
--default-site-id	MATOMO_DEFAULT_SITE_ID	—	Site used when the model doesn't specify one
--header	MATOMO_EXTRA_HEADERS	—	Extra HTTP headers (Name:Value, repeatable / comma-separated) — for auth proxies, Zero-Trust, multi-tenant setups
--timeout-secs	MATOMO_TIMEOUT_SECS	30	Per-request timeout
--max-response-chars	MATOMO_MAX_RESPONSE_CHARS	50000	Response budget before truncation
--http	MATOMO_HTTP_BIND	—	Serve MCP over streamable HTTP on this address instead of stdio (endpoint: http://<addr>/mcp)
--insecure	MATOMO_INSECURE	false	Accept 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-mcp	mcp-matomo
Tool set	15 curated tools + escape hatch	~70+ generated tools
Model context cost	Small, stable	Large, instance-dependent
Parameter types	Exact, hand-written enums/defaults	Inferred from parameter names
Startup	Instant (no network I/O)	Introspection round-trips (or cached spec file)
TLS verification	On by default	Disabled for introspection
Sub-directory installs	✅	Path is overwritten
Response size guard	Row 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

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

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.

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/.

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

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

cargo test                                   # 37 tests, fully offline (wiremock)
cargo clippy --all-targets -- -D warnings
cargo 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.