Umami MCP

npx add-mcp 'https://cloud.umami.is/mcp'

@umami/mcp

Servidor Model Context Protocol para análises do Umami. Permite que Claude, ChatGPT, Cursor e outros clientes MCP respondam perguntas sobre o tráfego do seu site usando ferramentas somente leitura que chamam a API do Umami por meio de @umami/api-client.

O servidor MCP nunca acessa um banco de dados; cada ferramenta passa pela API pública e pelas mesmas verificações de permissão de usuário/equipe que o aplicativo web.

Ferramentas

Ferramenta	Finalidade
list_websites	Encontre os sites que você pode acessar (chame primeiro para obter um websiteId).
get_website_daterange	Datas mais antigas e mais recentes com dados registrados.
get_website_stats	Pageviews, visitantes, visitas, taxa de rejeição, duração + período anterior.
get_website_traffic	Série temporal de pageviews/visitas por minuto, hora, dia, mês ou ano.
get_website_metrics	Principais páginas, referenciadores, canais, países, navegadores, dispositivos, UTM, eventos.
get_realtime	Visitantes ativos agora.
get_events	Eventos rastreados individuais (paginados).
get_event_stats	Totais de eventos personalizados + período anterior.
get_event_series	Contagens de eventos personalizados ao longo do tempo, agrupados por nome do evento.
get_event_properties	Nomes de propriedades de eventos personalizados, ou os valores de uma propriedade.
get_sessions	Sessões de visitantes (paginadas).
get_session_stats	Totais no nível da sessão: visitantes, visitas, pageviews, eventos, países.
get_annotations	Notas datadas na linha do tempo (lançamentos, campanhas) para explicar mudanças.
list_segments	Segmentos e coortes salvos; passe IDs via filters.segment / .cohort.
get_session	Uma sessão com sua linha do tempo de atividade e propriedades.
list_funnels	Funis salvos com suas etapas (obtenha um funnelId para run_funnel).
run_funnel	Funil de conversão a partir de um funnelId salvo ou etapas ad-hoc de página/evento.
get_goals	Metas salvas com conversões, visitantes e taxa para um intervalo.
run_journey	Caminhos mais comuns que os visitantes percorrem.
run_retention	Tabela de retenção de coortes.
run_attribution	Atribuição de primeiro/último clique para uma conversão.
get_revenue	Totais de receita, séries e detalhamentos.
get_performance	Core Web Vitals (LCP, INP, CLS, FCP, TTFB) percentis, tendência, detalhamento.

Todas as ferramentas são somente leitura. Datas estão em ISO 8601; os resultados são paginados com um limite máximo de tamanho de página.

Remoto: Umami Cloud

Conecte-se a https://cloud.umami.is/mcp usando sua chave de API Cloud existente:

Authorization: Bearer api_<your-cloud-api-key>

Clientes que suportam cabeçalhos personalizados podem usar x-umami-api-key em vez disso. Se ambos os cabeçalhos forem fornecidos, eles devem conter a mesma chave. Use um cliente que suporte configuração de chave de API ou cabeçalho bearer.

O MCP Cloud tem os mesmos requisitos de assinatura e permissões de site/equipe que a API Cloud. Todas as ferramentas chamam o gateway da API Cloud, que valida a chave e roteia as solicitações para sua região.

Remoto: auto-hospedado

Gere uma chave de API em Configurações → Chaves de API na sua instância do Umami e configure seu cliente MCP com o endpoint HTTP Streamable:

https://your-umami.example.com/mcp

Defina o cabeçalho de autorização usando sua chave:

Authorization: Bearer umami_<your-api-key>

Use um cliente que suporte tokens bearer ou cabeçalhos de autorização personalizados. O endpoint aceita chaves de API auto-hospedadas; tokens de login do navegador não são suportados. As ferramentas são somente leitura e respeitam as permissões existentes de usuário/equipe do proprietário da chave. Revogue a chave em Configurações para desconectar o acesso. O MCP está desabilitado por padrão. Defina MCP_ENABLED=1 para habilitar o endpoint.

Local / stdio

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_API_TOKEN": "umami_…"
      }
    }
  }
}

Variável	Descrição
UMAMI_URL	URL da instância auto-hospedada (/api é anexado).
UMAMI_API_URL	URL base completa da API em vez disso, ex.: https://api.umami.is/v1.
UMAMI_API_TOKEN	Chave de API ou token de login (auto-hospedado).
UMAMI_API_KEY	Chave de API do Umami Cloud.

Para stdio Cloud, defina UMAMI_API_KEY e omita UMAMI_URL e UMAMI_API_TOKEN:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": { "UMAMI_API_KEY": "api_<your-cloud-api-key>" }
    }
  }
}

Exemplos de prompts

• Mostre meus sites.
• Quantos visitantes example.com recebeu na semana passada?
• Quais foram as 10 páginas principais neste mês?
• Compare o tráfego deste mês com o mês anterior.
• De onde vem o tráfego?
• Quais eventos de inscrição ocorreram ontem?
• Mostre sessões para o usuário abc123.
• Quais planos de preço as pessoas selecionaram no evento de checkout no mês passado?
• Quantos eventos de inscrição foram disparados por dia nesta semana?
• Execute meu funil de checkout do mês passado.
• Como estamos indo em relação às nossas metas neste trimestre?
• Quais páginas têm o pior LCP em dispositivos móveis?
• O que aconteceu no dia em que o tráfego disparou?

Uso programático

import { UmamiClient } from '@umami/api-client';
import { createUmamiMcpServer } from '@umami/mcp';

const server = createUmamiMcpServer({
  client: new UmamiClient({ baseUrl, token }),
});

createUmamiMcpHttpHandler({ createClient }) retorna um manipulador HTTP Streamable para incorporação em qualquer framework web; o host verifica o token bearer e passa authInfo.