Umami MCP Server

Connect your Umami Analytics to any MCP client - Claude Desktop, VS Code, Cursor, Windsurf, Zed, Smithery, and more.

Prompts

Analytics & Traffic

"Give me a comprehensive analytics report for my website over the last 30 days"
"Which pages are getting the most traffic this month? Show me the top 10"
"Analyze my website's traffic patterns - when do I get the most visitors?"

User Insights

"Where are my visitors coming from? Break it down by country and city"
"What devices and browsers are my users using?"
"Show me the user journey - what pages do visitors typically view in sequence?"

Sessions & Replay

"How many sessions were recorded last month? List the most active ones"
"Walk me through what session did — the pages and events in order"
"Which recorded sessions came from mobile in Sweden?"

Real-time Monitoring

"How many people are on my website right now? What pages are they viewing?"
"Is my website experiencing any issues? Check if traffic has dropped significantly"

Content & Campaign Analysis

"Which blog posts should I update? Show me articles with declining traffic"
"How did my recent email campaign perform? Track visitors from the campaign UTM"
"Compare traffic from different social media platforms"

Quick Start

Option 1: Download Binary

Get the latest release for your platform from Releases

Option 2: Docker

hljs language-bash

docker run -i --rm \
  -e UMAMI_URL="https://your-instance.com" \
  -e UMAMI_USERNAME="username" \
  -e UMAMI_PASSWORD="password" \
  ghcr.io/macawls/umami-mcp-server

Option 3: Go Install

hljs language-bash

go install github.com/Macawls/umami-mcp-server@latest

Installs to ~/go/bin/umami-mcp-server (or $GOPATH/bin)

Setup

Pick one of the two approaches below based on your preference.

Remote (No Install)

A hosted instance is available at https://umami-mcp.macawls.dev/mcp. Connect directly from any MCP client that supports HTTP transport — no binary or Docker needed.

Credentials are passed via X-Umami-* headers on the initialize request.

Claude Desktop

Add to your config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

hljs language-json

{
  "mcpServers": {
    "umami": {
      "type": "http",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headersHelper": "echo X-Umami-Host: https://your-instance.com && echo X-Umami-Username: admin && echo X-Umami-Password: pass"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

hljs language-json

{
  "servers": {
    "umami": {
      "type": "http",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "${input:umami-username}",
        "X-Umami-Password": "${input:umami-password}"
      }
    }
  }
}

Claude Code

hljs language-bash

claude mcp add --transport http \
  --header "X-Umami-Host: https://your-instance.com" \
  --header "X-Umami-Username: admin" \
  --header "X-Umami-Password: pass" \
  umami https://umami-mcp.macawls.dev/mcp

Cursor

Add to .cursor/mcp.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "serverUrl": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

OpenCode

Add to opencode.json:

hljs language-json

{
  "mcp": {
    "umami": {
      "type": "remote",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

Other Clients

Any MCP client that supports Streamable HTTP can connect to https://umami-mcp.macawls.dev/mcp with credentials in X-Umami-Host, X-Umami-Username, and X-Umami-Password headers.

Local

Run the binary or Docker image locally. Credentials are set via environment variables.

Claude Desktop

Add to your config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json:

hljs language-json

{
  "servers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

hljs language-bash

claude mcp add \
  umami-mcp-server \
  -e UMAMI_URL="https://your-umami-instance.com" \
  -e UMAMI_USERNAME="your-username" \
  -e UMAMI_PASSWORD="your-password" \
  -- ~/go/bin/umami-mcp-server

Cursor

Add to .cursor/mcp.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Zed

Add to your Zed settings under assistant.mcp_servers:

hljs language-json

{
  "umami": {
    "command": "~/go/bin/umami-mcp-server",
    "env": {
      "UMAMI_URL": "https://your-umami-instance.com",
      "UMAMI_USERNAME": "your-username",
      "UMAMI_PASSWORD": "your-password"
    }
  }
}

Docker

For clients that use a command field (Claude Desktop, Cursor, etc.):

hljs language-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": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Tool	Description
`get_websites`	List all websites (call this first to get website IDs)
`get_stats`	Aggregated statistics — pageviews, visitors, bounces, total time
`get_pageviews`	Pageview and session counts grouped by time unit
`get_metrics`	Breakdown by page, referrer, browser, OS, device, country, etc.
`get_active`	Current active visitor count in real-time
`get_sessions`	List individual visitor sessions, with total count — the sessions session replay records
`get_session_stats`	Aggregated session totals — pageviews, visitors, visits, countries, events
`get_session_activity`	Ordered pageview/event timeline for a single session

Configuration

Environment Variables

Variable	Default	Description
`UMAMI_URL`	required	Your Umami instance URL (use `https://api.umami.is` for Umami Cloud)
`UMAMI_USERNAME`	required for self-hosted	Umami username
`UMAMI_PASSWORD`	required for self-hosted	Umami password
`UMAMI_API_KEY`	required for Umami Cloud	API key from your Umami Cloud account (alternative to username/password)
`UMAMI_TEAM_ID`		Team ID for team-based setups
`TRANSPORT`	`stdio`	Transport mode (`stdio` or `http`)
`PORT`	`8080`	HTTP server port
`ALLOWED_ORIGINS`	`*`	Comma-separated CORS allowed origins
`MAX_SESSIONS`	`1000`	Maximum concurrent HTTP sessions

Config File

Instead of environment variables, create a config.yaml file next to the binary:

hljs language-yaml

umami_url: https://your-umami-instance.com
username: your-username
password: your-password
team_id: your-team-id  # optional

For Umami Cloud, use an API key instead:

hljs language-yaml

umami_url: https://api.umami.is
api_key: your-api-key

Environment variables take priority over the config file.

Umami Cloud

Umami Cloud (the hosted version at cloud.umami.is) does not support username/password authentication. Use an API key from your Umami Cloud account settings and set UMAMI_URL=https://api.umami.is together with UMAMI_API_KEY=.... For HTTP transport, send the X-Umami-Api-Key header instead of X-Umami-Username/X-Umami-Password.

Team Websites

If your Umami instance uses teams and your websites are assigned to a team rather than individual users, get_websites may return an empty list. Set UMAMI_TEAM_ID to fetch websites from your team instead. For HTTP transport, use the X-Umami-Team-Id header.

You can find your team ID in your Umami dashboard under Settings > Teams.

Self-Hosting (HTTP Transport)

The server supports Streamable HTTP for remote deployments. Set TRANSPORT=http to expose a /mcp endpoint:

hljs language-bash

TRANSPORT=http PORT=9999 ./umami-mcp-server

Credentials are passed via X-Umami-* headers on the initialize request. The response includes a Mcp-Session-Id header for subsequent requests.

Docker defaults to HTTP mode:

hljs language-bash

docker run -p 8080:8080 ghcr.io/macawls/umami-mcp-server

Build from Source

hljs language-bash

git clone https://github.com/Macawls/umami-mcp-server.git
cd umami-mcp-server
go build -o umami-mcp

Troubleshooting

macOS binary won't run: xattr -c umami-mcp-server to remove quarantine
Linux binary won't run: chmod +x umami-mcp-server
Connection errors: Verify your Umami instance is accessible and credentials are correct
Tools not showing up: Check your MCP client logs, verify the binary path is absolute

License

MIT

Umami MCP Server

Connect your Umami Analytics to any MCP client - Claude Desktop, VS Code, Cursor, Windsurf, Zed, Smithery, and more.

Prompts

Analytics & Traffic

"Give me a comprehensive analytics report for my website over the last 30 days"
"Which pages are getting the most traffic this month? Show me the top 10"
"Analyze my website's traffic patterns - when do I get the most visitors?"

User Insights

"Where are my visitors coming from? Break it down by country and city"
"What devices and browsers are my users using?"
"Show me the user journey - what pages do visitors typically view in sequence?"

Sessions & Replay

"How many sessions were recorded last month? List the most active ones"
"Walk me through what session did — the pages and events in order"
"Which recorded sessions came from mobile in Sweden?"

Real-time Monitoring

"How many people are on my website right now? What pages are they viewing?"
"Is my website experiencing any issues? Check if traffic has dropped significantly"

Content & Campaign Analysis

"Which blog posts should I update? Show me articles with declining traffic"
"How did my recent email campaign perform? Track visitors from the campaign UTM"
"Compare traffic from different social media platforms"

Quick Start

Option 1: Download Binary

Get the latest release for your platform from Releases

Option 2: Docker

hljs language-bash

docker run -i --rm \
  -e UMAMI_URL="https://your-instance.com" \
  -e UMAMI_USERNAME="username" \
  -e UMAMI_PASSWORD="password" \
  ghcr.io/macawls/umami-mcp-server

Option 3: Go Install

hljs language-bash

go install github.com/Macawls/umami-mcp-server@latest

Installs to ~/go/bin/umami-mcp-server (or $GOPATH/bin)

Setup

Pick one of the two approaches below based on your preference.

Remote (No Install)

A hosted instance is available at https://umami-mcp.macawls.dev/mcp. Connect directly from any MCP client that supports HTTP transport — no binary or Docker needed.

Credentials are passed via X-Umami-* headers on the initialize request.

Claude Desktop

Add to your config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

hljs language-json

{
  "mcpServers": {
    "umami": {
      "type": "http",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headersHelper": "echo X-Umami-Host: https://your-instance.com && echo X-Umami-Username: admin && echo X-Umami-Password: pass"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

hljs language-json

{
  "servers": {
    "umami": {
      "type": "http",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "${input:umami-username}",
        "X-Umami-Password": "${input:umami-password}"
      }
    }
  }
}

Claude Code

hljs language-bash

claude mcp add --transport http \
  --header "X-Umami-Host: https://your-instance.com" \
  --header "X-Umami-Username: admin" \
  --header "X-Umami-Password: pass" \
  umami https://umami-mcp.macawls.dev/mcp

Cursor

Add to .cursor/mcp.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "serverUrl": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

OpenCode

Add to opencode.json:

hljs language-json

{
  "mcp": {
    "umami": {
      "type": "remote",
      "url": "https://umami-mcp.macawls.dev/mcp",
      "headers": {
        "X-Umami-Host": "https://your-instance.com",
        "X-Umami-Username": "admin",
        "X-Umami-Password": "pass"
      }
    }
  }
}

Other Clients

Any MCP client that supports Streamable HTTP can connect to https://umami-mcp.macawls.dev/mcp with credentials in X-Umami-Host, X-Umami-Username, and X-Umami-Password headers.

Local

Run the binary or Docker image locally. Credentials are set via environment variables.

Claude Desktop

Add to your config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json:

hljs language-json

{
  "servers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

hljs language-bash

claude mcp add \
  umami-mcp-server \
  -e UMAMI_URL="https://your-umami-instance.com" \
  -e UMAMI_USERNAME="your-username" \
  -e UMAMI_PASSWORD="your-password" \
  -- ~/go/bin/umami-mcp-server

Cursor

Add to .cursor/mcp.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

hljs language-json

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Zed

Add to your Zed settings under assistant.mcp_servers:

hljs language-json

{
  "umami": {
    "command": "~/go/bin/umami-mcp-server",
    "env": {
      "UMAMI_URL": "https://your-umami-instance.com",
      "UMAMI_USERNAME": "your-username",
      "UMAMI_PASSWORD": "your-password"
    }
  }
}

Docker

For clients that use a command field (Claude Desktop, Cursor, etc.):

hljs language-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": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Tool	Description
`get_websites`	List all websites (call this first to get website IDs)
`get_stats`	Aggregated statistics — pageviews, visitors, bounces, total time
`get_pageviews`	Pageview and session counts grouped by time unit
`get_metrics`	Breakdown by page, referrer, browser, OS, device, country, etc.
`get_active`	Current active visitor count in real-time
`get_sessions`	List individual visitor sessions, with total count — the sessions session replay records
`get_session_stats`	Aggregated session totals — pageviews, visitors, visits, countries, events
`get_session_activity`	Ordered pageview/event timeline for a single session

Configuration

Environment Variables

Variable	Default	Description
`UMAMI_URL`	required	Your Umami instance URL (use `https://api.umami.is` for Umami Cloud)
`UMAMI_USERNAME`	required for self-hosted	Umami username
`UMAMI_PASSWORD`	required for self-hosted	Umami password
`UMAMI_API_KEY`	required for Umami Cloud	API key from your Umami Cloud account (alternative to username/password)
`UMAMI_TEAM_ID`		Team ID for team-based setups
`TRANSPORT`	`stdio`	Transport mode (`stdio` or `http`)
`PORT`	`8080`	HTTP server port
`ALLOWED_ORIGINS`	`*`	Comma-separated CORS allowed origins
`MAX_SESSIONS`	`1000`	Maximum concurrent HTTP sessions

Config File

Instead of environment variables, create a config.yaml file next to the binary:

hljs language-yaml

umami_url: https://your-umami-instance.com
username: your-username
password: your-password
team_id: your-team-id  # optional

For Umami Cloud, use an API key instead:

hljs language-yaml

umami_url: https://api.umami.is
api_key: your-api-key

Environment variables take priority over the config file.

Umami Cloud

Team Websites

You can find your team ID in your Umami dashboard under Settings > Teams.

Self-Hosting (HTTP Transport)

The server supports Streamable HTTP for remote deployments. Set TRANSPORT=http to expose a /mcp endpoint:

hljs language-bash

TRANSPORT=http PORT=9999 ./umami-mcp-server

Credentials are passed via X-Umami-* headers on the initialize request. The response includes a Mcp-Session-Id header for subsequent requests.

Docker defaults to HTTP mode:

hljs language-bash

docker run -p 8080:8080 ghcr.io/macawls/umami-mcp-server

Build from Source

hljs language-bash

git clone https://github.com/Macawls/umami-mcp-server.git
cd umami-mcp-server
go build -o umami-mcp

Troubleshooting

macOS binary won't run: xattr -c umami-mcp-server to remove quarantine
Linux binary won't run: chmod +x umami-mcp-server
Connection errors: Verify your Umami instance is accessible and credentials are correct
Tools not showing up: Check your MCP client logs, verify the binary path is absolute

License

MIT

umami-mcp-server

Umami MCP Server

Prompts

Analytics & Traffic

User Insights

Sessions & Replay

Real-time Monitoring

Content & Campaign Analysis

Quick Start

Option 1: Download Binary

Option 2: Docker

Option 3: Go Install

Setup

Remote (No Install)

Local

Available Tools

Configuration

Environment Variables

Config File

Umami Cloud

Team Websites

Self-Hosting (HTTP Transport)

Build from Source

Troubleshooting

License

Similar Packages

umami-mcp-server

Umami MCP Server

Prompts

Analytics & Traffic

User Insights

Sessions & Replay

Real-time Monitoring

Content & Campaign Analysis

Quick Start

Option 1: Download Binary

Option 2: Docker

Option 3: Go Install

Setup

Remote (No Install)

Local

Available Tools

Configuration

Environment Variables

Config File

Umami Cloud

Team Websites

Self-Hosting (HTTP Transport)

Build from Source

Troubleshooting

License

Similar Packages