matomo-mcp

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

14 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?

Related MCP server: Matomo MCP Server

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

🧭 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

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 (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

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

🛠️ Development

cargo test                                   # 33 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.