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

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

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

go install github.com/Macawls/umami-mcp-server@latest
# Or specific version
go install github.com/Macawls/[email protected]

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

Configure Your MCP Client

Claude Desktop

Add to your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.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"
      }
    }
  }
}

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

{
  "mcpServers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "${input:umami_url}",
        "UMAMI_USERNAME": "${input:umami_username}",
        "UMAMI_PASSWORD": "${input:umami_password}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "umami_url",
      "description": "Umami instance URL"
    },
    {
      "type": "promptString",
      "id": "umami_username",
      "description": "Umami username"
    },
    {
      "type": "promptString",
      "id": "umami_password",
      "description": "Umami password",
      "password": true
    }
  ]
}

Restart Claude Desktop to load the server.

VS Code (GitHub Copilot)

Enable agent mode and add MCP servers to access Umami from Copilot.

For workspace: Create .vscode/mcp.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"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "umami_url",
      "description": "Umami instance URL"
    },
    {
      "type": "promptString",
      "id": "umami_username",
      "description": "Umami username"
    },
    {
      "type": "promptString",
      "id": "umami_password",
      "description": "Umami password",
      "password": true
    }
  ],
  "servers": {
    "umami": {
      "command": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "${input:umami_url}",
        "UMAMI_USERNAME": "${input:umami_username}",
        "UMAMI_PASSWORD": "${input:umami_password}"
      }
    }
  }
}

Access via: Chat view → Agent mode → Tools button

Other MCP Clients

Cursor: Ctrl/Cmd + Shift + P → "Cursor Settings" → MCP section

Windsurf: Settings → MCP Settings → Add MCP Server
Config location: %APPDATA%\windsurf\mcp_settings.json (Windows)

Zed: Settings → assistant.mcp_servers

Cline: VS Code Settings → Extensions → Cline → MCP Servers

All use similar JSON format as above. Docker and secure prompts work the same way.

Available Tools

• get_websites - List all your websites
• get_stats - Get visitor statistics
• get_pageviews - View page traffic over time
• get_metrics - See browsers, countries, devices, and more
• get_active - Current active visitors

Remote Usage (No Install)

A hosted instance is available at https://umami-mcp.macawls.dev/mcp. You can connect to it 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. Query parameters are also supported as a fallback but deprecated.

Claude Desktop

Claude Desktop does not support custom headers, so credentials are passed as query parameters:

{
  "mcpServers": {
    "umami": {
      "type": "url",
      "url": "https://umami-mcp.macawls.dev/mcp?umamiHost=https://your-instance.com&umamiUsername=admin&umamiPassword=pass"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json with credentials in headers:

{
  "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

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:

{
  "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:

{
  "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:

{
  "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.

Transport Modes

The server supports two transport modes, controlled by the TRANSPORT environment variable:

Stdio (default)

Used by local MCP clients like Claude Desktop, VS Code, Cursor, etc. This is the default — no extra configuration needed.

HTTP

The server exposes a /mcp endpoint that speaks Streamable HTTP. Use this for self-hosting or remote deployments.

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

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

curl -X POST "http://localhost:9999/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Umami-Host: https://analytics.example.com" \
  -H "X-Umami-Username: admin" \
  -H "X-Umami-Password: pass" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

The response includes a Mcp-Session-Id header to use for subsequent requests.

Environment Variables

Docker

When using Docker, the image defaults to HTTP mode:

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

For local stdio usage with Docker, override the transport:

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

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 the UMAMI_TEAM_ID environment variable to fetch websites from your team instead:

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

For HTTP transport, pass the team ID via the X-Umami-Team-Id header.

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

Alternative Configuration

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

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

Environment variables take priority over the config file.

Build from Source

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

Troubleshooting

Binary won't run

• macOS: Run xattr -c umami-mcp-server to remove quarantine
• Linux: Run chmod +x umami-mcp-server to make executable

Connection errors

• Verify your Umami instance is accessible
• Check your credentials are correct

Tools not showing up

• Check your MCP client logs for errors
• Verify the binary path is absolute
• Try running the binary directly to check for errors

License

MIT