A GoatCounter MCP for agents that read the numbers and act on them
Connect one GoatCounter site code and API token, and 15 nodes land on the canvas: total pageviews with the per-day series behind them, top pages, per-page referrers, the six dashboard breakdowns with drill-down, the path catalog, site reads and provisioning, raw exports with an incremental cursor, and server-side pageview counting. An AI agent can pull last week's traffic, compare it with the week before, and open a task when something moves, without anyone opening the dashboard.
What the GoatCounter MCP connector does
The GoatCounter connector for Mattering Automations is 15 nodes on GoatCounter API v0, which is complete coverage of the documented API: every operation the vendor publishes is a node, nothing is padded and nothing is skipped. Eleven nodes read and four act. The reporting half carries GoatCounter: Get Total Pageviews (totals plus one row per day), GoatCounter: Get Pageviews By Path (the dashboard's main table), GoatCounter: Get Path Referrers, GoatCounter: Get Breakdown Stats and GoatCounter: Get Breakdown Detail across browsers, systems, locations, languages, campaigns, top referrers and screen sizes, and GoatCounter: List Paths, which turns a URL into the path id the reporting endpoints filter on. The rest is sites, exports, and server-side counting.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. Ask an agent which pages grew this month and it runs GoatCounter: Get Pageviews By Path over two windows; ask where the new traffic came from and it runs GoatCounter: Get Path Referrers on the page that moved. The same nodes are steps on an automation canvas, so the answer can become a scheduled report, a database row, or a task rather than a chat message that scrolls away.
One structural fact shapes the whole connector, and it is easier to explain than to hide. GoatCounter addresses each site by its own subdomain, and it mints an API token inside one site rather than at the account level. The reporting endpoints carry no site parameter at all: they report on whichever site the host resolved to. So the site code lives on the credential next to the token, the two belong together, and reporting on a second site means a second credential. That is also how a GoatCounter user already thinks about it, one key per site. Self-hosting is a first-class case here rather than a courtesy: the same field takes a full https base URL, so an instance at stats.example.com works exactly like a goatcounter.com subdomain.
Two of the fifteen nodes are irreversible and both say so on the node itself. GoatCounter: Send Pageviews writes rows this API cannot delete, and it accepts a created_at in the past, so a mistake can change numbers you have already reported on. GoatCounter: Update Site replaces the whole settings object rather than merging it, and its data_retention setting permanently purges pageviews older than the window you set. GoatCounter publishes no delete-site and no delete-pageview endpoint, so neither of those has an undo from here.
One connection, three surfaces
- Visual automations. Drag GoatCounter nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every GoatCounter node, ready to drop on the canvas
15 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 11
GoatCounter: Download Export
Download a finished export's file. GoatCounter serves it gzip-compressed; this node decompresses it and returns the text at data.content, with data.format, data.bytes and data.truncated alongside. Exports of a busy site are large, so the text is capped and data.truncated says whether it was cut, which makes this suitable for a small site's full history or for an incremental export started with start_from_hit_id, and not for pulling millions of rows through a workflow. Check GoatCounter: Get Export first: downloading before finished_at is set returns an error rather than a partial file. Needs the export permission.
GoatCounter: Get Breakdown Detail
Drill into one row of a breakdown: pick Firefox from browsers and get its versions, pick a country from locations and get its regions, pick a campaign and get its sources. Same response shape as the breakdown node, one level deeper. Supports browsers, systems, locations, campaigns, toprefs and sizes; languages has no detail view. Needs the statistics permission.
GoatCounter: Get Breakdown Stats
One of GoatCounter's dashboard breakdowns for a date range: browsers, systems, locations, languages, campaigns, toprefs or sizes. Returns data.stats as one row per value with an id, a human-readable name and a count, ordered by count descending, plus data.more. Pick the breakdown with the page field. Needs the statistics permission.
GoatCounter: Get Current User
Get the account behind the stored API key, plus the key's own permissions: data.user carries the email, settings and timezone, and data.token carries the key name and its permission bits. Takes no parameters and needs no permission bit of its own, which makes it the connector's credential health check and the first call to run when another node returns 403.
GoatCounter: Get Export
Check on an export started with GoatCounter: Start Export. The job is finished when data.finished_at is set and data.error is null; the response also carries the row count, the file size, a SHA256 hash of the file, and the last_hit_id to use as the next run's cursor. Poll this before downloading. Needs the export permission.
GoatCounter: Get Pageviews By Path
Top pages for a date range: data.hits is one row per path with its total count, title, whether it is an event, and a nested per-day series at hits[].stats carrying daily, weekly, monthly and hourly values. This is the closest thing GoatCounter has to its dashboard's main table. Rows are ordered by count descending and cut off at limit, so the result is a TOP N and not the whole site unless data.more is false. Needs the statistics permission.
GoatCounter: Get Path Referrers
Where the traffic to ONE page came from: data.refs is one row per referrer with its name and count, ordered by count descending, plus a ref_scheme telling you whether it was a link, a search engine, a campaign or something else. Offset paginated, so unlike the other stat listers this one can be walked to completion. Needs the statistics permission. Rate limit note: fanning this out across many paths is the easiest way to trip GoatCounter's 4 requests per second cap.
GoatCounter: Get Site
Fetch one site by numeric id: code, custom domain, link domain, state, whether it has ever received data, and its full settings object including the data retention window. Needs the site read permission. Field-name trap, and this is the wire format rather than a mistake in this description: a site's settings come back under the key setttings, with three t's, because that is the JSON tag GoatCounter ships. Read data.setttings; data.settings resolves to nothing.
GoatCounter: Get Total Pageviews
Total counts for a date range, plus the per-day series behind them: data.total for everything, data.total_events for events only, data.total_utc for the same total computed over UTC days instead of the site's timezone, and data.stats as one row per day carrying that day's number and a 24-slot hourly array. This is the node to hang a traffic chart on. Needs the statistics permission.
GoatCounter: List Paths
List every path and event GoatCounter has recorded for this site, at data.paths, with no statistics attached: id, path, title, and whether it is an event rather than a pageview. These ids are what the stats nodes filter on, so this is the node that turns a URL into something the reporting endpoints accept. Cursor-paginated with after; data.more says whether another page exists. Needs the statistics permission.
GoatCounter: List Sites
List the site this API key belongs to and every child site created under it, at data.sites, each with its numeric id, code (the subdomain), custom domain, link domain and settings. Needs the site read permission. Note this does not switch which site the stats nodes report on: those always follow the credential's own site code, so reporting on a child site means storing a second credential. Field-name trap, and this is the wire format rather than a mistake in this description: a site's settings come back under the key setttings, with three t's, because that is the JSON tag GoatCounter ships. Read data.setttings; data.settings resolves to nothing.
Action nodes 4
GoatCounter: Create Site
Create a new site as a CHILD of the site this API key belongs to, which is how one GoatCounter account tracks several domains. The code becomes the new site's subdomain and must be globally unique across GoatCounter. Needs the site create permission. Reversible, but not from here: GoatCounter ships no delete-site API endpoint, so removing a site is done in its web interface under Settings.
GoatCounter: Send Pageviews
Record pageviews or events server-side, without a browser and without the tracking script: useful for counting API hits, downloads, emails opened, or anything that never renders a page. Send up to a few hundred hits per call, each with at least a path. Needs the count permission. IRREVERSIBLE: GoatCounter has no endpoint that deletes pageviews, and created_at can write into periods you have already reported on, so a mistake here permanently changes the site's numbers and can only be undone from GoatCounter's own purge screen. Point it at a test site first.
GoatCounter: Start Export
Start a background export of this site's raw pageviews, which is the only way to get row-level data out of GoatCounter (the stats endpoints only ever return aggregates). Returns immediately with the export's id and its last_hit_id; the file is not ready yet. Poll GoatCounter: Get Export until finished_at is set, then fetch it with GoatCounter: Download Export. Keep last_hit_id and pass it back as start_from_hit_id next time to export only what is new. Needs the export permission. Creates a file on GoatCounter's side and changes no analytics data.
GoatCounter: Update Site
Update a site's settings, custom domain or link domain. Needs the site update permission. Two warnings, both irreversible. First, settings is a WHOLE-OBJECT REPLACE: keys you leave out are reset rather than kept, so read the site first and send the complete object back with your change applied. Second, settings.data_retention permanently deletes every pageview older than that many days, with no undo and no API route that could restore them. Request bodies spell the key settings; responses spell it setttings with three t's.
Connecting GoatCounter takes one credential
GoatCounter tokens are created inside a site, under User then API in that site's own settings, and they are presented to that site's own subdomain. That is why the credential holds two values together: the site code (the subdomain of your dashboard, so example for https://example.goatcounter.com) and the token itself. A self-hosted instance puts its full https base URL in the same field. There is one gate here worth understanding before you build anything, because it produces the connector's most common support question. A GoatCounter token carries per-route permission checkboxes chosen at creation: count, export, site read, site create, site update, and statistics. A missing permission answers 403, not 401. GoatCounter's API help states this plainly: 401 means the key is missing or incorrect, 403 means it does not have the needed permissions. Only one route in the whole API is permission-free, and it is the one the connection test uses, so a token with every box unticked passes Test Connection and then fails everywhere else. Tick statistics for the six reporting nodes and the path catalog, site read for the site readers, site create and site update for the two site writers, export for the three export nodes, and count for server-side pageviews. On rate: GoatCounter documents 4 requests per second, reported back on every response in the X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers, which is low enough to matter for any workflow that fans out across many paths. On the hosted service itself, GoatCounter's own wording is that goatcounter.com is currently offered for free for reasonable public usage; the vendor names sending millions of pageviews per day as outside that, recommends self-hosting for more serious purposes, and publishes no quota, no paid hosted plan and no service level agreement. Treat it as the discretionary arrangement the vendor describes rather than a commercial guarantee, and use the self-hosted path for anything high volume. This connector supports both.
Open your GoatCounter dashboard, go to User then API, and create a token. Tick the permissions the nodes you plan to use need: statistics for reporting, site read for the site nodes, export for exports, count for server-side pageviews.
Note your site code while you are there. It is the subdomain in your dashboard URL, so example for https://example.goatcounter.com. Self-hosting instead? Use your full https base URL, for example https://stats.example.com.
In Mattering Automations, open Connectors, click Add Connector, choose GoatCounter, and create a credential with the site code and the token.
Click Test Connection. Mattering calls GoatCounter: Get Current User against your own host, which is the one route no permission bit guards, so a valid token always passes it. The success message reports the token's permission list back, which is how you check that the boxes you needed were actually ticked.
All 15 GoatCounter nodes appear in the canvas palette. Run GoatCounter: List Paths first: it returns the path ids the referrer and detail nodes filter on.
Common uses for the GoatCounter MCP
Traffic reporting that lands where the rest of the work lives
GoatCounter: Get Total Pageviews returns the totals for a date range plus one row per day behind them, which is the node to hang a chart on. GoatCounter: Get Pageviews By Path returns the top pages with a per-day series nested inside each row. Because these are nodes rather than a script, the numbers flow into the next step: a Mattering database that keeps a running history, a weekly summary drafted by an agent, a task that opens only when a page moves further than it should have. One caveat to design around, and the node says it too: the top pages list is ordered by count and cut off at the limit you set, so it is a top N rather than the whole site unless the response says there is nothing more.
Find the page that moved, then find out why
The two-step that GoatCounter is unusually good at. GoatCounter: Get Pageviews By Path shows which page changed, then GoatCounter: Get Path Referrers takes that one page and returns where its traffic came from, one row per referrer with a scheme telling you whether it was a link, a search engine or a campaign. That node is offset paginated, so unlike the other stat readers it can be walked to completion rather than truncated. It is also the easiest way to trip the 4 requests per second limit if you fan it out across every path at once, so pace it or narrow it to the pages that actually moved.
The six dashboard breakdowns, with drill-down
GoatCounter: Get Breakdown Stats covers browsers, systems, locations, languages, campaigns, top referrers and screen sizes for a date range, each as one row per value with an id, a readable name and a count. GoatCounter: Get Breakdown Detail goes one level deeper on a single row: pick a browser and get its versions, pick a country and get its regions, pick a campaign and get its sources. Languages is the one exception, and it is the vendor's rather than ours: there is no per-language detail view, which the node says. This is the surface an agent uses to answer a question like which browsers the new traffic arrived on without anyone building a report first.
Watch for a traffic change on a schedule
GoatCounter has no webhooks, no alerting endpoint and no scheduled-report API, so a spike or drop watch is built by polling rather than by subscription, and that is worth saying plainly rather than implying an event stream that does not exist. The cheap shape is a schedule trigger, GoatCounter: Get Total Pageviews over yesterday, a comparison against the numbers already stored in a Mattering database, and a condition that opens a task or posts to a channel only when the delta is bigger than you expect. Time zones matter for the comparison: GoatCounter's start and end are in the SITE's timezone, not UTC, which is exactly why the totals node also returns a separate UTC-aligned figure.
Raw rows out, incrementally
The stats endpoints only ever return aggregates, so raw pageview rows come out through the export family. GoatCounter: Start Export begins a background export and returns immediately with an id and a last_hit_id, GoatCounter: Get Export is polled until the job reports finished, and GoatCounter: Download Export fetches the file and decompresses it. Keep the last_hit_id and pass it back as the next run's starting point and each run exports only what is new, which is the sane pattern for a busy site: downloading a whole dataset dump through a workflow is not. Two things the nodes are honest about: downloading before the job finishes returns an error rather than a partial file, so poll first, and the download caps what it pulls into a node output and reports whether it was cut.
Server-side counting for things that never render a page
GoatCounter: Send Pageviews records hits without a browser and without the tracking script, which is how you count API calls, file downloads, or an email that was opened. It is flagged irreversible and it is worth respecting the flag: GoatCounter publishes no endpoint that deletes pageviews, and the node accepts a created_at in the past, so a mistake permanently changes a period you have already reported on and can only be undone from GoatCounter's own purge screen. Point it at a test site first. There is a second, quieter trap the node documents: GoatCounter rejects a hit that carries neither a session nor both a user agent and an IP, and turning that guard off makes every hit from a server look like the same visitor, so visitor numbers stop meaning what they meant.
Example: A Monday traffic digest that only interrupts someone when it should
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a weekly schedule fires on Monday morning.
GoatCounter: Get Total Pageviews runs for the last seven days and again for the seven days before that, so the run has both a number and something to compare it against. Both windows are expressed in the site's own timezone, which is the timezone GoatCounter's start and end parameters use.
GoatCounter: Get Pageviews By Path returns the top pages for the same week, and the rows land in a Mattering database next to last week's, so the history builds itself rather than living in a spreadsheet someone maintains.
A condition compares the two totals. Inside the expected range, the run writes the row and stops there.
Outside it, GoatCounter: Get Path Referrers runs on the two or three pages that moved most, which is where the answer usually is: a link from somewhere new, a campaign that started, or a search engine sending different traffic.
Matter drafts a short summary from the numbers and the referrers, and a task opens with it attached, assigned to whoever owns the site. Nobody is interrupted on a normal week.
GoatCounter MCP questions, answered
What GoatCounter operations are supported?
All 15 of them, which is complete coverage of GoatCounter's documented API: 11 read nodes and 4 action nodes. Reading: current user and token permissions, list sites, get site, list paths, total pageviews with the per-day series, pageviews by path, per-page referrers, the dashboard breakdowns, breakdown drill-down, export status, and export download. Acting: create site, update site, start export, and send pageviews server-side. The only documented route not shipped as its own node is the PATCH form of the site update, because GoatCounter registers it as the same handler with the same body as the POST form, so a second node would do exactly what the first one does.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively. The nodes also run as steps on an automation canvas, on a schedule or off a trigger, with nobody present, which is the part a chat-only setup cannot do.
Does GoatCounter publish its own MCP server?
Not as of August 2026. GoatCounter is a small, source-available project maintained by one person, and no first-party MCP server appears in its documentation or its repository, so there is no vendor server to compare this connector against. That can change, and if it does it is worth knowing what this connector offers that a local developer tool typically does not: the nodes run on a schedule or off a trigger without anyone present, they chain with every other connector in one workflow, the credential is held once in a shared workspace rather than in each person's own client config, and the two irreversible nodes are flagged as such so you can gate them.
My token is valid but every node returns 403. What is wrong?
A permission checkbox, almost certainly. GoatCounter tokens carry per-route permissions chosen at creation, and its API help is explicit that 401 means the key is missing or incorrect while 403 means the key does not have the needed permission. Get Current User is the only route no permission guards, and it is the route the connection test uses, so a token with everything unticked passes the test and then fails on all fourteen other nodes. Run GoatCounter: Get Current User from the canvas: it returns the token's own permission list, so you can see exactly what was ticked. Then either tick the missing permission on that token in GoatCounter under User then API, or mint a new one. The mapping is per node family: statistics for the reporting nodes and the path catalog, site read for the site readers, site create and site update for the two site writers, export for the export family, count for server-side pageviews.
Does it work with a self-hosted GoatCounter?
Yes, and this is a deliberate design point rather than an afterthought, because GoatCounter is source-available and the vendor itself recommends self-hosting for more serious purposes. Put your full https base URL in the site code field instead of a subdomain, for example https://stats.example.com, and every node behaves identically. The field accepts a bare hostname, a full URL, a trailing slash or a pasted API path and normalizes them all back to the origin. Plain http is refused rather than silently upgraded, because that would put your token on the wire in the clear.
Can one credential report on more than one site?
No, and the reason is structural rather than a limitation of the connector. GoatCounter's reporting endpoints take no site parameter: total pageviews, pageviews by path, referrers, breakdowns and the path catalog all report on whichever site the host resolved to, and the host comes from the credential's site code. So a second site needs a second credential, which is also how GoatCounter itself works, since a token is minted inside one site. GoatCounter: List Sites will still show the site this key belongs to and any child sites created under it, and GoatCounter: Create Site can add one, but neither switches which site the reporting nodes read.
What are GoatCounter's rate limits?
GoatCounter documents 4 requests per second, and reports the current state back on every response in the X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers, the last being the seconds until the limit resets. That is low enough to shape how you build: a workflow that walks every path through GoatCounter: Get Path Referrers will hit it, so narrow the list to the pages you care about or pace the loop. The connector does not silently retry a rate-limited call; the status code surfaces in the node output so the workflow can decide what to do.
Can an AI agent change or delete my analytics data?
Two of the fifteen nodes can, and both are flagged so you can gate them. GoatCounter: Send Pageviews writes rows this API cannot delete, and because it accepts a timestamp in the past it can alter a period you have already reported on. GoatCounter: Update Site is worse in one specific way: its settings field is a whole-object replace rather than a merge, so keys you leave out are reset instead of kept, and its data retention setting permanently purges pageviews older than the window you set, with no API route that could restore them. Read the site first and send the complete object back with your change applied. The honest guardrails here are structural: keep agents on the eleven read nodes, put the two writers behind a condition or an approval task, and point anything experimental at a test site, because GoatCounter publishes neither a delete-site nor a delete-pageview endpoint to undo with.
What is not available through this connector?
Things GoatCounter does not expose, rather than things left out. There are no funnels, retention, cohorts, segments or user profiles: the entire reporting surface is counts by path, by referrer, and by six dimension breakdowns. There are no custom event properties, since a GoatCounter event is a path-shaped name with an optional title rather than a property bag. There are no goals or conversions. There are no webhooks, no alerting and no scheduled-report endpoint, so a traffic watch is built by polling on a schedule. There is no delete-site endpoint (removal happens in GoatCounter's own web interface), no delete-pageview endpoint, and no list-exports endpoint, which is why an export id only ever comes from the node that started the export. One field-name trap worth carrying into any workflow that reads a site: GoatCounter serializes a site's settings under a key spelled with three t's on the way out while the update request body spells it with two, so a read-modify-write reads one key and writes the other. Every affected node says so.
Put GoatCounter to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. GoatCounter is a product of its respective owner; Mattering is an independent platform.