Umami MCP Server

Umami MCP Server

Conecte seu Umami Analytics a qualquer cliente MCP - Claude Desktop, VS Code, Cursor, Windsurf, Zed, Smithery e outros.

Prompts

Analytics e Tráfego

• "Me dê um relatório abrangente de analytics para meu site nos últimos 30 dias"
• "Quais páginas estão recebendo mais tráfego este mês? Mostre as 10 principais"
• "Analise os padrões de tráfego do meu site - quando recebo mais visitantes?"

Insights de Usuários

• "De onde vêm meus visitantes? Divida por país e cidade"
• "Quais dispositivos e navegadores meus usuários estão usando?"
• "Mostre a jornada do usuário - quais páginas os visitantes normalmente visualizam em sequência?"

Sessões e Replay

• "Quantas sessões foram gravadas no mês passado? Liste as mais ativas"
• "Me explique o que a sessão fez — as páginas e eventos em ordem"
• "Quais sessões gravadas vieram de dispositivos móveis na Suécia?"

Monitoramento em Tempo Real

• "Quantas pessoas estão no meu site agora? Quais páginas estão visualizando?"
• "Meu site está enfrentando algum problema? Verifique se o tráfego caiu significativamente"

Análise de Conteúdo e Campanhas

• "Quais posts do blog devo atualizar? Mostre artigos com tráfego em declínio"
• "Como foi o desempenho da minha última campanha de e-mail? Rastreie visitantes do UTM da campanha"
• "Compare o tráfego de diferentes plataformas de mídia social"

Início Rápido

Opção 1: Baixar Binário

Obtenha a versão mais recente para sua plataforma em Releases

Opção 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

Opção 3: Instalação via Go

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

Instala em ~/go/bin/umami-mcp-server (ou $GOPATH/bin)

Configuração

Escolha uma das duas abordagens abaixo com base na sua preferência.

Remoto (Sem Instalação)

Uma instância hospedada está disponível em https://umami-mcp.macawls.dev/mcp. Conecte-se diretamente de qualquer cliente MCP que suporte transporte HTTP — sem necessidade de binário ou Docker.

As credenciais são passadas via cabeçalhos X-Umami-* na solicitação initialize.

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

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

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

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

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

Local

Execute o binário ou a imagem Docker localmente. As credenciais são definidas via variáveis de ambiente.

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

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

{
  "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": "~/go/bin/umami-mcp-server",
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "your-username",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

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

Ferramentas Disponíveis

Configuração

Variáveis de Ambiente

Arquivo de Configuração

Em vez de variáveis de ambiente, crie um arquivo config.yaml ao lado do binário:

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

Para Umami Cloud, use uma chave de API em vez disso:

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

As variáveis de ambiente têm prioridade sobre o arquivo de configuração.

Umami Cloud

O Umami Cloud (a versão hospedada em cloud.umami.is) não suporta autenticação por nome de usuário/senha. Use uma chave de API das configurações da sua conta Umami Cloud e defina UMAMI_URL=https://api.umami.is junto com UMAMI_API_KEY=.... Para transporte HTTP, envie o cabeçalho X-Umami-Api-Key em vez de X-Umami-Username/X-Umami-Password.

Sites de Equipe

Se sua instância Umami usa equipes e seus sites são atribuídos a uma equipe em vez de usuários individuais, get_websites pode retornar uma lista vazia. Defina UMAMI_TEAM_ID para buscar sites da sua equipe. Para transporte HTTP, use o cabeçalho X-Umami-Team-Id.

Você pode encontrar seu ID de equipe no painel do Umami em Configurações > Equipes.

Self-Hosting (Transporte HTTP)

O servidor suporta Streamable HTTP para implantações remotas. Defina TRANSPORT=http para expor um endpoint /mcp:

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

As credenciais são passadas via cabeçalhos X-Umami-* na solicitação initialize. A resposta inclui um cabeçalho Mcp-Session-Id para solicitações subsequentes.

O Docker usa o modo HTTP por padrão:

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

Compilar a partir do Código-Fonte

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

Solução de Problemas

• Binário macOS não executa: xattr -c umami-mcp-server para remover a quarentena
• Binário Linux não executa: chmod +x umami-mcp-server
• Erros de conexão: Verifique se sua instância Umami está acessível e se as credenciais estão corretas
• Ferramentas não aparecem: Verifique os logs do seu cliente MCP, confirme se o caminho do binário é absoluto

Licença

MIT