Skip to content
Get packs

Guide · Agent skill

How to use the Matomo Analytics Reporter agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The seo-matomo skill is an add-on for an AI agent that lets it read website traffic reports from Matomo, a self-hosted or cloud web analytics tool often chosen as a privacy-focused alternative to Google Analytics. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs before it works. You need an existing Matomo instance and an API token; without them the skill cannot return any data.

Matomo Analytics ReporterAgriciDaniel/claude-seo · MIT

Quick start

  1. 1Confirm you have a Matomo instance and token. Make sure you have the instance URL and an API token_auth with view access to the sites you want to analyse.
  2. 2Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills.
  3. 3Configure credentials. Store MATOMO_URL and MATOMO_API_TOKEN in ~/.config/claude-seo/matomo.json or as environment variables, and optionally set MATOMO_SITE_ID.
  4. 4Run the connection check. Run the matomo_auth.py --check command to confirm the URL and token work before requesting reports.
  5. 5Ask for a report. Make a natural request such as a traffic summary for the last 28 days, or use /seo matomo top-pages.
  6. 6Review the table output. Check the labelled Matomo Reporting API (live) tables and read keyword data with the anonymised share in mind.

What the skill makes the agent do

Agent skills are instruction packages that give an AI agent a specific capability. This one teaches the agent to query the Matomo Reporting API and summarise the results. Once installed, the agent can run organic traffic, top pages, device, country, referrer and keyword reports for a site you own access to.

The skill is a reporting substitute for Google Analytics 4, not a replacement for Google Search performance data. It covers visits, pages and referrers. Google Search Console questions belong to a different skill, seo-google.

  • Organic traffic trend
  • Top landing pages
  • Device and country breakdowns
  • Referrer split
  • Search keywords, with the anonymised share shown

Install the seo-matomo skill

Download the ZIP from the skill's page on this site and unzip it into one of two locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the ZIP there.

The skill's own setup notes say to run extensions/matomo/install.sh (or install.ps1 on Windows) to configure it. That script is part of the claude-seo plugin, so the plugin scripts must be present.

Configure your Matomo connection

The skill needs three things: your Matomo instance URL, an API token_auth with view access to the sites you want to analyse, and optionally a default site ID. You can store them in ~/.config/claude-seo/matomo.json, which should be readable only by you (mode 0600), or set them as environment variables.

The variables are MATOMO_URL, MATOMO_API_TOKEN and MATOMO_SITE_ID. The site ID is optional; if you set it, you do not need to pass a site ID on every request.

  • Matomo instance URL, for example https://analytics.example.com
  • API token_auth with view access on the sites you analyse
  • Optional default site ID (MATOMO_SITE_ID)

Check the connection before you ask for reports

Run the authentication check first. It confirms the skill can reach your instance and that the token works. If the check fails, fix the configuration before asking for any report.

The check runs through the claude-seo runner script, so the plugin's scripts folder must be available.

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run matomo_auth.py --check

Trigger the skill with natural requests

You do not need to memorise commands. The skill responds to phrases such as "Matomo", "self-hosted analytics", "GA4 alternative", "Matomo Reporting" and "Piwik". You can also ask in German with "analytics ohne Google". Name the report you want and, if you have several sites, the site.

The skill also has slash-style commands. These map to the underlying reports: check, organic, top-pages, device, country, referrers and keywords. The organic command accepts a site ID.

  • /seo matomo check
  • /seo matomo organic [site-id]
  • /seo matomo top-pages
  • /seo matomo device
  • /seo matomo country
  • /seo matomo referrers
  • /seo matomo keywords

Options and output

Every report command accepts --days (default 28), --limit, --site-id and --json. The site ID falls back to MATOMO_SITE_ID if you do not pass one.

The agent presents time-series, device and country data as tables and labels the source as Matomo Reporting API (live). For keywords, pay attention to the anonymized_share_pct figure. Many keywords appear as "(not provided)" because of browser privacy and Matomo's anonymisation rules; this is expected, not a fault.

  • --days: look-back window, default 28
  • --limit: number of rows
  • --site-id: override the default site
  • --json: machine-readable output

Fix a private or local Matomo address

Every request passes through claude-seo's SSRF guard. Private, loopback and link-local addresses are refused by default. If your instance is on an internal host, name it in the CLAUDE_SEO_LOCAL_TARGETS allowlist using host or host:port. The allowlist covers only the top-level instance URL, and cloud metadata addresses stay refused even if listed.

Do not disable the guard or edit url_safety.py. The allowlist is the supported route.

export CLAUDE_SEO_LOCAL_TARGETS="matomo.internal:8080"

What people use it for

  • Get a 28-day organic traffic trend for a self-hosted site without using Google Analytics.
  • List top landing pages and compare them with the previous period.
  • Break down visits by device and by country for a regulated or EU-based organisation.
  • See which referrers send traffic and which search keywords are visible, with the anonymised share noted.
  • Run a cross-check during a site audit when both GA4 and Matomo are configured.

Frequently asked questions

Is the Matomo analytics skill free?

The skill is published under the MIT licence, as stated on its page. Matomo itself is a separate product, so your hosting or Matomo Cloud plan is a separate cost to consider.

What do I need before I can use it?

You need a Matomo instance URL and an API token_auth with view access to the sites you analyse. Without these, nothing works. Optionally, set a default site ID.

How do I install the seo-matomo skill?

Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload it under Settings, Capabilities, Skills.

Why does my Matomo instance get refused?

Private, loopback and link-local addresses are refused by default by the SSRF guard. Add the host or host:port to the CLAUDE_SEO_LOCAL_TARGETS allowlist, as the error message suggests. Do not disable the guard.

Why do many keywords show as (not provided)?

Browser privacy settings and Matomo's anonymisation rules hide many search keywords. The skill reports the anonymized_share_pct so you can see how much data is hidden.

Can this replace Google Search Console?

No. The skill covers reporting on visits, pages and referrers. Google Search Console, CrUX and indexing questions are handled by the seo-google skill.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits teams that already run Matomo, whether self-hosted or in the cloud, and want an agent to pull SEO-relevant traffic reports without Google Analytics. It is a poor fit if you have no Matomo instance and token, or if your questions are about Google Search performance, which needs the seo-google skill instead.

Download the skill