Umami MCP server

Servidor MCP que expõe o Umami analytics (Cloud + auto-hospedado)

Documentação

Servidor MCP Umami

Servidor MCP que expõe análises somente leitura da API Umami Cloud atual e do Umami 3.x auto-hospedado.

Matriz de suporte

Implantação	Suporte	Raiz da API	Autenticação
Umami Cloud (atual)	Suportado	`https://api.umami.is/v1`	Chave de API
Umami 3.x auto-hospedado	Suportado	`https://host.example/api`	Usuário/senha
Umami 2.x auto-hospedado	Não suportado; qualquer integração futura será separada	—	—
Umami 1.x	Não suportado	—	—

O sufixo /v1 pertence à URL da API Cloud atual. Isso não significa que este servidor suporta a versão 1 do aplicativo Umami auto-hospedado.

Requisitos e comando de execução

Python 3.11+
uv

Execute o pacote publicado diretamente:

uvx umami-mcp-server

Configuração

Variáveis de ambiente:

UMAMI_API_KEY: chave da API Umami Cloud.
UMAMI_USERNAME: usuário do Umami 3.x auto-hospedado.
UMAMI_PASSWORD: senha do Umami 3.x auto-hospedado.
UMAMI_API_BASE: opcional; o padrão é https://api.umami.is/v1. Para implantações auto-hospedadas, defina a raiz da API incluindo /api.

Escolha exatamente um modo de autenticação: uma chave de API Cloud ou usuário e senha auto-hospedados. As chaves de API Cloud usam o esquema documentado Authorization: Bearer; o Umami 3.x auto-hospedado padrão não suporta chaves de API.

Exemplo de configuração MCP para Cloud:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_API_KEY": "YOUR_UMAMI_CLOUD_API_KEY",
        "UMAMI_API_BASE": "https://api.umami.is/v1"
      },
      "enabled": true
    }
  }
}

Umami 3.x auto-hospedado:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_USERNAME": "YOUR_USERNAME",
        "UMAMI_PASSWORD": "YOUR_PASSWORD",
        "UMAMI_API_BASE": "https://your-umami.example/api"
      },
      "enabled": true
    }
  }
}

Ferramentas

get_websites: retorna uma página de sites. page >= 1 e 1 <= page_size <= 100.
get_stats: resumo de pageviews, visitantes, visitas, rejeições, tempo total e comparação.
get_pageviews: séries temporais de pageviews e sessões.
get_metrics: métricas compactas ou expandidas. 1 <= limit <= 500 e 0 <= offset <= 10000.
get_active: visitantes ativos no momento.

Todo website_id, segmento e identificador de coorte é validado como UUID antes de uma solicitação HTTP ser enviada.

Intervalos de tempo

Parâmetros de data e hora aceitam datetimes ISO. Valores sem fuso horário são interpretados como UTC. As quatro regras de intervalo são:

Entradas	Intervalo
nenhuma	agora menos sete dias → agora
apenas `end_at`	sete dias antes de `end_at` → `end_at`
apenas `start_at`	`start_at` → agora
ambas	intervalo explícito

O fim deve ser posterior ao início. As unidades de pageview são minute, hour, day, month, e year. Os fusos horários devem ser nomes IANA válidos, como UTC ou Europe/Rome. As comparações são prev ou yoy.

Métricas e filtros

Tipos de métricas:

path, fullPath, entry, exit, referrer, domain, title, query,
event, tag, hostname, utmSource, utmMedium, utmCampaign,
utmContent, utmTerm, browser, os, device, screen, language,
country, city, region, distinctId, channel

Filtros documentados do Umami 3:

path, referrer, title, query, browser, os, device, country,
region, city, language, hostname, tag, event, distinctId,
utmSource, utmMedium, utmCampaign, utmContent, utmTerm,
segment, cohort

A entrada da ferramenta usa snake_case para distinct_id e os filtros UTM; o servidor serializa os nomes camelCase upstream automaticamente.

Confiabilidade e erros seguros

Um único cliente HTTP e pool de conexões é compartilhado durante o ciclo de vida do servidor MCP. Tokens do modo de login são compartilhados, login/atualização concorrentes são sincronizados, e uma solicitação pode realizar no máximo três envios de análises e uma atualização de token. Solicitações GET repetem apenas falhas de rede, timeouts, limites de taxa e respostas transitórias de 500, 502, 503 e 504. Retry-After é respeitado até 60 segundos.

Erros são expostos como categorias controladas: autenticação, limite de taxa, timeout, rede, falha upstream e resposta inválida. Mensagens públicas e logs excluem corpos de resposta, credenciais, cabeçalhos, URLs completas de consulta e valores brutos de exceção HTTP/Pydantic.

Cache e observabilidade

Na revisão MCP atual, o catálogo estático tools/list tem uma dica pública de cache de cinco minutos. A ordem das ferramentas e o conteúdo do esquema são determinísticos, e o catálogo não contém dados do Umami, IDs de sites ou credenciais. A serialização do protocolo legado permanece inalterada e não inclui campos de cache.

O SDK MCP já rastreia operações MCP recebidas. O Umami MCP Server adiciona um span filho para cada solicitação lógica de análises do Umami, um span filho de login quando necessário, e métricas para duração, erros, repetições, limites de taxa e atualizações de token. Apenas o W3C Trace Context é propagado para o Umami; o baggage MCP não é encaminhado.

O pacote base usa apenas a API OpenTelemetry, então a instrumentação permanece sem efeito sem um SDK e exportador. Instale a pilha opcional com umami-mcp-server[otel], configure-a externamente, ou desative-a explicitamente com OTEL_SDK_DISABLED=true. Consulte o guia de observabilidade para configuração, nomes exportados, política de redação e exemplos OTLP.

Desenvolvimento

uv sync --dev
uv run ruff format . --check
uv run ruff check .
uv run pyright
uv run pytest

O teste opcional de contrato ao vivo da Cloud requer UMAMI_LIVE_CLOUD_API_KEY e UMAMI_LIVE_CLOUD_WEBSITE_ID; UMAMI_LIVE_CLOUD_API_BASE pode substituir a raiz padrão da Cloud.