Goatcounter

Interaja com a API de análise web do Goatcounter.

GitHub

Documentação

Servidor MCP Goatcounter

smithery badge

Visão Geral

Este projeto fornece um servidor Model Context Protocol (MCP) para interagir com a API de análise web do Goatcounter. Ele permite que modelos de linguagem ou outros clientes MCP consultem facilmente estatísticas e informações do Goatcounter usando uma interface de ferramentas padronizada.

O servidor é construído usando Python e a biblioteca FastMCP. Ele lê o código do seu site Goatcounter e a chave da API a partir de variáveis de ambiente para autenticação.

Recursos

  • Fornece ferramentas para a maioria dos endpoints da API do Goatcounter.
  • Gerencia a configuração da chave da API e do código do site por meio de variáveis de ambiente (GOATCOUNTER_API_KEY, GOATCOUNTER_CODE).
  • Inicialização preguiçosa do cliente da API: as ferramentas podem ser listadas mesmo que as credenciais da API ainda não estejam configuradas.
  • Tratamento de Limite de Taxa: Implementa novas tentativas automáticas com backoff ao encontrar limites de taxa da API (HTTP 429).
    • Prioriza o cabeçalho X-Rate-Limit-Reset para espera, se fornecido pela API.
    • Recorre ao backoff exponencial (começando em 1 segundo) com jitter aleatório se o cabeçalho estiver indisponível ou for inválido.
    • Tenta novamente até 5 vezes antes de falhar.
  • Executa diretamente usando a ferramenta de linha de comando fastmcp.

Instalação

Opção 1: Instalação via Smithery (Recomendado)

Para instalar o servidor MCP X (Twitter) para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude

Opção 2: Instalar do PyPI

A maneira mais fácil de instalar goatcounter-mcp-server é via PyPI:

pip install goatcounter-mcp-server

Ou instale diretamente do repositório:

pip install git+https://github.com/rafaljanicki/goatcounter-mcp-server.git

Opção 3: Instalar a partir do código-fonte

Se você preferir instalar a partir do repositório de código-fonte:

  1. Clone o repositório:

    git clone https://github.com/rafaljanicki/goatcounter-mcp-server
cd goatcounter-mcp-server

  2. Crie um ambiente virtual:

    python3.13 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

  3. Instale as dependências: Instale o FastMCP e outros pacotes necessários:

    pip install -r requirements.txt

  4. Configure as variáveis de ambiente: Copie o arquivo de exemplo .env.example para .env:

    cp .env.example .env

    Edite o arquivo .env e adicione seus dados do Goatcounter (veja a seção Variáveis de Ambiente abaixo).

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

  • GOATCOUNTER_CODE: O código do seu site Goatcounter (a parte do subdomínio, ex.: 'mycoolsite').
  • GOATCOUNTER_API_KEY: Seu token da API do Goatcounter. Você pode gerar um no seu site Goatcounter em Configurações -> Tokens da API. Certifique-se de que ele tenha as permissões necessárias para as ações da API que você pretende usar.

Você pode definir essas variáveis diretamente no seu ambiente ou colocá-las em um arquivo .env na raiz do projeto.

Executando o Servidor

Opção 1: Usando o Script CLI

O projeto define um script CLI goatcounter-mcp-server.

Se instalado do PyPI:

goatcounter-mcp-server

Se instalado do código-fonte com uv:

uv run goatcounter-mcp-server

Opção 2: Usando FastMCP Diretamente (Somente Código-fonte)

Se você instalou do código-fonte e prefere executar o servidor usando o modo de desenvolvimento do FastMCP:

fastmcp dev src/goatcounter_mcp_server/server.py

Usando com Claude Desktop

Para usar este servidor MCP com Claude Desktop, você precisa configurar o Claude para se conectar ao servidor. Siga estes passos:

Passo 1: Instalar Node.js

O Claude Desktop usa Node.js para executar servidores MCP. Se você não tiver o Node.js instalado:

  • Baixe e instale o Node.js em nodejs.org.
  • Verifique a instalação: 
    node --version

Passo 2: Localizar a Configuração do Claude Desktop

O Claude Desktop usa um arquivo claude_desktop_config.json para configurar servidores MCP.

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Se o arquivo não existir, crie-o.

Passo 3: Configurar o Servidor MCP

Edite claude_desktop_config.json para incluir o servidor goatcounter-mcp-server. Substitua /path/to/goatcounter-mcp-server pelo caminho real para o diretório do seu projeto (se instalado do código-fonte) ou o caminho para o seu executável Python (se instalado do PyPI).

Se instalado do PyPI:

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "goatcounter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

Se instalado do código-fonte com uv:

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/goatcounter-mcp-server",
        "run",
        "goatcounter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}
  • "command": "goatcounter-mcp-server": Usa o script CLI diretamente se instalado do PyPI.
  • "env": Se instalado do PyPI, você pode precisar fornecer variáveis de ambiente diretamente na configuração (já que não há arquivo .env). Se instalado do código-fonte, o arquivo .env será usado.
  • "env": {"PYTHONUNBUFFERED": "1"}: Garante que a saída não seja armazenada em buffer para melhor registro de logs no Claude.

Passo 4: Reiniciar o Claude Desktop

  • Saia completamente do Claude Desktop.
  • Reabra o Claude Desktop para carregar a nova configuração.

Passo 5: Verificar a Conexão

  • Abra o Claude Desktop.
  • Procure por um ícone de martelo ou conector na área de entrada (canto inferior direito). Isso indica que as ferramentas MCP estão disponíveis.
  • Clique no ícone para ver as ferramentas disponíveis de goatcounter-mcp-server

Documentação da API: Ferramentas Disponíveis

As seguintes ferramentas MCP estão disponíveis:

Ferramenta: Goatcounter_get_me

Obtenha informações sobre o usuário atual do Goatcounter e a chave da API associada ao GOATCOUNTER_API_KEY configurado.

  • Parâmetros: Nenhum
  • Retorna: object - Informações sobre o usuário e o token.

Ferramenta: Goatcounter_list_sites

Liste todos os sites Goatcounter acessíveis com a chave da API atual.

  • Parâmetros: Nenhum
  • Retorna: object - Uma lista de sites acessíveis.

Ferramenta: Goatcounter_list_paths

Obtenha uma visão geral dos caminhos rastreados neste site (sem estatísticas).

  • Parâmetros:
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Selecione apenas caminhos após este ID de caminho, para paginação.
  • Retorna: object - Uma lista de caminhos e informações de paginação.

Ferramenta: Goatcounter_get_stats_total

Obtenha o número total de visualizações de página e visitantes únicos para o site dentro de um período especificado.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
  • Retorna: object - Estatísticas totais ou estatísticas diárias se daily for verdadeiro.

Ferramenta: Goatcounter_get_stats_hits

Liste estatísticas de páginas (visualizações de página e visitantes por caminho).

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de caminhos e informações de paginação.

Ferramenta: Goatcounter_get_stats_refs

Liste estatísticas de referenciadores.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de referenciadores e informações de paginação.

Ferramenta: Goatcounter_get_stats_browsers

Liste estatísticas de navegadores.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de navegadores e informações de paginação.

Ferramenta: Goatcounter_get_stats_systems

Liste estatísticas de sistemas operacionais.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de SO e informações de paginação.

Ferramenta: Goatcounter_get_stats_sizes

Liste estatísticas de tamanho de tela.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de tamanho de tela e informações de paginação.

Ferramenta: Goatcounter_get_stats_locations

Liste estatísticas de localização.

  • Parâmetros:
    • start (string, opcional): Data de início (AAAA-MM-DD ou relativa, ex.: '7 dias atrás').
    • end (string, opcional): Data de término (AAAA-MM-DD ou relativa, ex.: 'ontem').
    • filter (string, opcional): Filtrar caminhos (ex.: '/blog*').
    • daily (booleano, opcional): Mostrar estatísticas diárias em vez de totais (padrão: falso).
    • limit (inteiro, opcional): Limite o número de resultados retornados (1-200, padrão 20).
    • after (inteiro, opcional): Cursor de paginação.
  • Retorna: object - Uma lista de estatísticas de localização e informações de paginação.

Uso

  1. Defina as Variáveis de Ambiente: Crie um arquivo .env na raiz do seu projeto ou defina as variáveis de ambiente diretamente:

    GOATCOUNTER_CODE=your_site_code
GOATCOUNTER_API_KEY=your_goatcounter_api_key

    Você pode gerar uma chave da API nas configurações da sua conta Goatcounter.

  2. Execute com FastMCP: Integre este servidor com sua configuração FastMCP. Consulte a documentação do FastMCP para obter detalhes sobre como conectar servidores MCP.

    O servidor registra ferramentas com o prefixo Goatcounter (ex.: Goatcounter.list_sites).

Desenvolvimento

  • Instale as dependências de desenvolvimento: pip install -e ".[dev]" (se as dependências de desenvolvimento estiverem especificadas em pyproject.toml)
  • Este projeto usa hatch para construção.

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.