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?

🚀 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 Code

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\):

{

"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):

{

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

{

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

{

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

Docker (any client)

{

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

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

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

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

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 transp