matomo-analytics

Matomo MCP Server

An MCP (Model Context Protocol) server that acts as a client to the Matomo Analytics API. It exposes Matomo analytics data as MCP tools, allowing any MCP-compatible LLM client (Claude Desktop, Claude Code, etc.) to query your Matomo instance using natural language.

In other words: it's an MCP server (tools over stdio) and a Matomo API client (HTTP requests) in one.

• Direct connection to your Matomo instance, no remote proxy
• 23 analytics tools: traffic, pages, search, performance, traffic sources, bulk batching, row evolution, segment discovery, and Live-API-backed counting
• Segment filtering on every time-based tool, including a device shortcut for mobile/desktop slicing
• matomo_count_visits_by_segment bypasses the segment-archiving trap (works even when the API token lacks process_new_segment)
• matomo_batch runs multiple reports in a single HTTP round-trip
• Custom date ranges via period=range + date=YYYY-MM-DD,YYYY-MM-DD
• Server-side response shaping: hideColumns, showColumns, filter_truncate, filter_offset, format_metrics
• Docker ready or run with Node.js
• Credentials stay local, never sent to third parties
• Retry logic with exponential backoff and timeout handling
• Supports self-signed certificates (common for internal servers)

Installation

Option 1: Docker

git clone https://github.com/lucaspretti/matomo-mcp-client
cd matomo-mcp-client
docker build -t matomo-mcp-server .
cp .env.example .env
# Edit .env with your Matomo URL and API token

Option 2: Node.js

git clone https://github.com/lucaspretti/matomo-mcp-client
cd matomo-mcp-client
npm install

Configuration

Environment Variables

Copy .env.example to .env and fill in your values:

Variable	Required	Description
MATOMO_HOST	Yes	Your Matomo instance URL
MATOMO_TOKEN_AUTH	Yes	Matomo API token (Settings > Personal > Security > Auth Tokens)
MATOMO_DEFAULT_SITE_ID	No	Default site ID (default: 1)
REQUEST_TIMEOUT	No	Request timeout in ms (default: 30000)
RETRY_COUNT	No	Retry attempts (default: 3)
RETRY_DELAY	No	Initial retry delay in ms (default: 1000)

MCP Client Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json):

Docker

{
  "mcpServers": {
    "matomo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/.env",
        "matomo-mcp-server"
      ]
    }
  }
}

Node.js

{
  "mcpServers": {
    "matomo": {
      "command": "node",
      "args": ["/absolute/path/to/matomo-mcp-client.js"],
      "env": {
        "MATOMO_HOST": "https://matomo.example.com",
        "MATOMO_TOKEN_AUTH": "your_token",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  }
}

Restart your MCP client after saving the configuration.

Available Tools

Traffic

Tool	Description
matomo_get_visits	Visit summary: unique visitors, total visits, actions, bounce rate, avg time
matomo_get_live_counters	Real-time visitor counters for the last N minutes
matomo_get_last_visits	Detailed info on recent visits: pages, referrer, device, location

Pages

Tool	Description
matomo_get_top_pages	Most visited page URLs with hits, time spent, load times
matomo_get_page_titles	Most visited pages by title
matomo_get_entry_pages	Top landing pages where visitors enter the site
matomo_get_exit_pages	Top exit pages where visitors leave the site

Site Search

Tool	Description
matomo_get_search_keywords	Keywords searched on the site's internal search
matomo_get_search_no_results	Search keywords that returned no results (content gaps)

Performance

Tool	Description
matomo_get_page_performance	Page load times: network, server, DOM processing, total
matomo_get_devices	Visitor device types: desktop, smartphone, tablet
matomo_get_browsers	Visitor browsers: Chrome, Firefox, Safari, Edge

Traffic Sources

Tool	Description
matomo_get_referrers	Referring websites sending traffic
matomo_get_search_engines	Search engines: Google, Bing, DuckDuckGo
matomo_get_ai_assistants	AI assistants: ChatGPT, Perplexity, Claude, Gemini
matomo_get_campaigns	All traffic sources overview including campaigns