get_websitesLABSCO SUMMARY
Analytics questions answered without opening the dashboard.
It covers both halves of the picture — the aggregate numbers and the individual session timelines — so a question like "which of my posts is losing traffic and what do those visitors do next" can be answered in one pass.
What it is
A single Go binary that speaks to a Umami instance, self-hosted or Cloud, and exposes the analytics surface as tools. It runs over stdio locally, or as a Streamable HTTP service with credentials passed in headers, and there is a hosted instance you can point at without installing anything.
What you get
get_websites— the websites you have, which is where the IDs for everything else come fromget_stats— pageviews, visitors, bounces and total time for a periodget_pageviews— pageview and session counts grouped by time unitget_metrics— the breakdown by page, referrer, browser, OS, device or countryget_active— how many people are on the site right nowget_sessions— individual visitor sessions with a total count, the same ones session replay recordsget_session_stats— aggregated session totals across pageviews, visitors, visits, countries and eventsget_session_activity— the ordered pageview and event timeline for one session
Requirements
For a self-hosted Umami: UMAMI_URL plus UMAMI_USERNAME and UMAMI_PASSWORD. Umami Cloud does not accept username and password — use UMAMI_API_KEY with UMAMI_URL set to https://api.umami.is. If your websites belong to a team rather than to you, get_websites comes back empty until you set UMAMI_TEAM_ID. Install by downloading a release binary, go install, or the container image; a config.yaml next to the binary works instead of environment variables, which take priority over it. TRANSPORT=http exposes a /mcp endpoint on PORT, default 8080, where credentials arrive as X-Umami-* headers on the initialize request. On macOS, xattr -c clears the quarantine flag if the binary will not start.
Setup effort
One command plus a key — go install github.com/Macawls/umami-mcp-server@latest, then supply credentials
USE CASES
01
Getting the month in one answer
Pull the top-line stats and the pageview series, then break them down by page and referrer, instead of clicking through four dashboard views.
02
Finding out where your visitors are
Break the traffic down by country, city, device and browser to see who is actually reading.
03
Checking whether something is wrong right now
Read the live active count and the pages being viewed, then compare it against the recent series to see if traffic dropped.
04
Following one visitor through the site
List the sessions, pick one, and read its ordered pageview and event timeline.
05
Deciding which articles to refresh
Compare page-level metrics across two periods to find the posts whose traffic is sliding.
06
Measuring a campaign
Filter by referrer and UTM to see what a specific email or social push actually brought in.
8 tools
Listed in project docs. Your client may show a different list.
get_statsget_pageviewsget_metricsget_activeget_sessionsget_session_statsget_session_activityBEFORE YOU INSTALL
What to know first
Tools you get
8 tools named in the project's documentation.
Requires
- UMAMI_URL in your environment
- UMAMI_USERNAME and UMAMI_PASSWORD (self-hosted Umami), or UMAMI_API_KEY (Umami Cloud)
Where it runs
Of the 8 documented setups, 6 run the server on your machine and 2 connect to a hosted endpoint.
INSTALLATION
Connect your client
Server setup
go install
TERMINAL
go install github.com/Macawls/umami-mcp-server@latestHosted endpoint
ENDPOINT URL
https://umami-mcp.macawls.dev/mcpAdd this hosted endpoint to your MCP client using the credentials listed under Requirements.
MCP Clients
Claude Desktop, Cursor, Windsurf
JSON
{
"mcpServers": {
"umami": {
"command": "~/go/bin/umami-mcp-server",
"env": {
"UMAMI_URL": "<YOUR_UMAMI_URL>",
"UMAMI_USERNAME": "<YOUR_UMAMI_USERNAME>",
"UMAMI_PASSWORD": "<YOUR_UMAMI_PASSWORD>"
}
}
}
}~/go/bin/umami-mcp-server has to be written as the binary's full path: the client starts the command directly, not through a shell, so ~ is not expanded. go install puts it in ~/go/bin (or $GOPATH/bin).
For Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
VS Code
VS CODE · JSON
{
"servers": {
"umami": {
"command": "~/go/bin/umami-mcp-server",
"env": {
"UMAMI_URL": "<YOUR_UMAMI_URL>",
"UMAMI_USERNAME": "<YOUR_UMAMI_USERNAME>",
"UMAMI_PASSWORD": "<YOUR_UMAMI_PASSWORD>"
}
}
}
}~/go/bin/umami-mcp-server has to be written as the binary's full path: the client starts the command directly, not through a shell, so ~ is not expanded. go install puts it in ~/go/bin (or $GOPATH/bin).
For Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add umami-mcp-server -e UMAMI_URL="<YOUR_UMAMI_URL>" -e UMAMI_USERNAME="<YOUR_UMAMI_USERNAME>" -e UMAMI_PASSWORD="<YOUR_UMAMI_PASSWORD>" -- ~/go/bin/umami-mcp-serverFor Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
Any MCP client — Docker
ANY MCP CLIENT — DOCKER · JSON
{
"mcpServers": {
"umami": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"UMAMI_URL",
"-e",
"UMAMI_USERNAME",
"-e",
"UMAMI_PASSWORD",
"ghcr.io/macawls/umami-mcp-server"
],
"env": {
"UMAMI_URL": "<YOUR_UMAMI_URL>",
"UMAMI_USERNAME": "<YOUR_UMAMI_USERNAME>",
"UMAMI_PASSWORD": "<YOUR_UMAMI_PASSWORD>"
}
}
}
}For clients that use a command field, such as Claude Desktop and Cursor.
For Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
OpenCode — remote
OPENCODE — REMOTE · JSON
{
"mcp": {
"umami": {
"type": "remote",
"url": "https://umami-mcp.macawls.dev/mcp",
"headers": {
"X-Umami-Host": "<YOUR_UMAMI_HOST>",
"X-Umami-Username": "admin",
"X-Umami-Password": "pass"
}
}
}
}For Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
Any MCP client — remote
ANY MCP CLIENT — REMOTE · JSON
{
"mcpServers": {
"umami-mcp-server": {
"url": "https://umami-mcp.macawls.dev/mcp",
"headers": {
"X-Umami-Host": "<YOUR_UMAMI_HOST>",
"X-Umami-Username": "admin",
"X-Umami-Password": "pass"
}
}
}
}For Umami Cloud, set UMAMI_API_KEY (from your Umami Cloud account settings) and UMAMI_URL=https://api.umami.is instead of UMAMI_USERNAME and UMAMI_PASSWORD; over HTTP, send the X-Umami-Api-Key header instead.
