Como Começar com o Servidor MCP do PostHog

Pronto para turbinar seu jogo de dados com IA? O PostHog MCP Server permite que você gerencie as análises do PostHog — como criar anotações ou consultar tendências de usuários — usando linguagem natural em ferramentas como Cline ou Cursor. Eu o coloquei para funcionar em apenas alguns minutos, e é uma virada de jogo total! Neste tutorial, instalaremos o PostHog MCP Server no Cline no VS Code e no Cursor, exploraremos seus recursos incríveis e veremos por que o PostHog supera o Google Analytics para análises de código aberto. Vamos mergulhar na magia do PostHog MCP Server!

O que é o PostHog MCP Server?

O **PostHog MCP Server** é um servidor de código aberto do Protocolo de Contexto de Modelo (MCP) que conecta assistentes de IA (como Cline ou Cursor) à plataforma de análise do PostHog por meio de comandos de linguagem natural. Ele permite tarefas como criar anotações, gerenciar projetos, consultar insights e alternar feature flags — tudo sem tocar na interface do usuário do PostHog. Os principais recursos incluem:

• **Gerenciamento de Projetos**: Liste e gerencie projetos PostHog.
• **Anotações**: Adicione notas com carimbo de data/hora para eventos (por exemplo, lançamentos de produtos).
• **Consultas de Insights**: Analise o comportamento do usuário (por exemplo, tendências de inscrição).
• **Feature Flags**: Controle e consulte feature flags dinamicamente.
• **Rastreamento de Erros**: Depure erros diretamente em sua IDE.

É um “item obrigatório” para automação de análises, com mais de 34 estrelas no GitHub mostrando o amor da comunidade. Pronto para experimentá-lo? Vamos lá

Por que usar o PostHog MCP Server?

O **PostHog MCP Server** simplifica os fluxos de trabalho de análise com automação impulsionada por IA. Veja por que ele é incrível:

• **Linguagem Natural**: Gerencie análises com comandos simples.
• **Integração**: Funciona com Claude Desktop, VS Code, Cursor e muito mais.
• **Código Aberto** (a melhor parte): Gratuito, personalizável e impulsionado pela comunidade.
• **Privacidade em Primeiro Lugar**: Ao contrário do Google Analytics, o PostHog oferece opções de auto-hospedagem para controle total dos dados.

Comparado ao Google Analytics, o PostHog se destaca por sua transparência de código aberto, flexibilidade de auto-hospedagem e suíte de produtos completa (análises, replay de sessão, feature flags). O Google Analytics frequentemente exige integrações de terceiros e carece do foco em privacidade do PostHog, tornando o **PostHog MCP Server** uma alternativa amigável para desenvolvedores em equipes modernas.

Eu o usei para anotar um lançamento de produto em segundos — muito mais rápido do que clicar em painéis!

Como instalar e usar o PostHog MCP Server: Guia passo a passo

Vamos instalar o **PostHog MCP Server** no Cline no VS Code e no Cursor, e depois testá-lo com exemplos. Você precisará de Python, uma chave de API do PostHog e uma IDE. Não é necessário ser um guru de análise — apenas siga!

1. Pré-requisitos

• **Python**: 3.8+ (`python3 --version`).
• **uv**: Gerenciador de pacotes Python (`pip install uv`).
• **VS Code/Cursor**: Versão mais recente com a extensão Cline.
• **Chave de API do PostHog**: Obtenha uma em app.posthog.com/settings (Chave de API Pessoal).
• **Docker**: Opcional para configuração em contêiner (`docker --version`).
• **Espaço em Disco**: ~500MB para o repositório e dependências.

2. Clone o Repositório PostHog MCP

Abra seu terminal e clone o repositório:

git clone https://github.com/PostHog/mcp.git
cd mcp

Isso baixa um projeto de ~5MB. Levei alguns segundos no Wi-Fi.

3. Instale o PostHog MCP Server com Cline no VS Code

• **Configure o Ambiente Virtual**:

uv venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate  # Windows
uv pip install .

• **Configure a Chave de API**:
  Crie um arquivo `.env` na raiz do projeto:

echo "PERSONAL_API_KEY=your-personal-api-key" > .env

Substitua `your-personal-api-key` pela sua chave de API do PostHog (que você pode obter no site oficial deles).

• **Instale o Cline**:
  No VS Code, vá para Extensões (Ctrl+Shift+X), instale o **Cline** e abra o painel de bate-papo do Cline (Ctrl+Shift+P, “Cline: Abrir Bate-papo”).

• **Adicione o Servidor MCP**:
  Comando para o Cline:

Install the PostHog MCP Server using uv and configure it with my API key.

O Cline executa `uv run posthog_mcp` e atualiza `~/.aws/amazonq/mcp.json`:

{
  "mcpServers": {
    "posthog": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp", "run", "posthog_mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Substitua `/path/to/mcp` pelo caminho do seu repositório (por exemplo, `/home/user/mcp`).

O servidor MCP também pode ser encontrado no marketplace MCP do Cline. Basta ir lá e procurar por "PostHog", depois clicar em instalar.

O Cline realizará a instalação automaticamente para você

• **Verificar**: Execute `/tools` no bate-papo do Cline para listar as ferramentas (por exemplo, `create_annotation`, `list_projects`). Vê o ícone dos servidores MCP no Cline? Você está pronto.

4. Instale o PostHog MCP Server com o Cursor

• **Clonar e Instalar**: Repita a clonagem e a configuração do ambiente virtual da Etapa 2.
• **Configure o Cursor**:
  Abra o Cursor, vá para Configurações > Ferramentas e Integrações > Ferramentas MCP > Adicionar um Servidor MCP Personalizado, e adicione a configuração do servidor a `.cursor/mcp.json`:

{
  "mcpServers": {
    "posthog": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/mcp", "run", "posthog_mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Encontre o caminho do `uv` com `which uv` (macOS/Linux) ou `where uv` (Windows).

• **Reinicie o Cursor**: Clique no botão de atualização em Configurações > Ferramentas e Integrações > Ferramentas MCP.
• **Verificar**: Pergunte ao Cursor: “Listar ferramentas disponíveis do PostHog MCP Server.” Ele deve mostrar `create_annotation`, `list_projects`, etc.

5. Teste os Recursos do PostHog MCP Server

• **Criar uma Anotação**:
  No Cline (VS Code) ou Cursor, digite:

Create a PostHog annotation in project 53497 for March 20th, 2025, with the description 'Launched new user onboarding flow' using the PostHog MCP Server.

O servidor chama a API do PostHog, adicionando a anotação. Verifique app.posthog.com para confirmar.

• **Consultar Insights**:
  Comando:

Show the trend of user sign-ups in project 98765 over the last 30 days using 
the PostHog MCP Server.

O servidor busca dados estruturados (por exemplo, JSON com tendências de inscrição). Exemplo de saída:

{
  "insight": "user_signups",
  "project_id": 98765,
  "data": [
    {"date": "2025-06-01", "count": 120},
    {"date": "2025-06-02", "count": 135}
  ]
}

Executei isso e obtive dados limpos em ~5 segundos — super elegante!

6. Configuração em Contêiner (Opcional)

Para uma configuração Docker:

docker run -i --rm -e PERSONAL_API_KEY=your-personal-api-key ghcr.io/metorial/mcp-container--posthog--posthog-mcp--posthog-mcp posthog-mcp

Adicione ao `mcp.json` do Cline/Cursor:

{
  "mcpServers": {
    "posthog": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/metorial/mcp-container--posthog--posthog-mcp--posthog-mcp", "posthog-mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Reinicie e verifique como acima. A limpeza do Docker (`--rm`) me poupou espaço em disco

7. Solução de Problemas Comuns

• **Sem Ícone de Martelo**:
• Verifique os logs: `~/Library/Logs/Claude/mcp*.log` (macOS) ou `%APPDATA%\Claude\logs` (Windows).
• Certifique-se de que os caminhos em `mcp.json` são absolutos.
• **Erros de Chave de API**:
• Verifique as permissões da chave em app.posthog.com/settings.
• Use variáveis de ambiente, não chaves codificadas.
• **Servidor Não Iniciado**:
• Execute `uv run posthog_mcp` manualmente para verificar erros.
• Certifique-se de ter Python 3.8+ e dependências (`uv pip install .`).
• **Precisa de Ajuda?** Verifique github.com/PostHog/mcp ou X para dicas.

Por que o PostHog Supera o Google Analytics

O **PostHog MCP Server** do PostHog se integra à sua plataforma, que supera o Google Analytics em:

• **Código Aberto**: Auto-hospede gratuitamente, ao contrário do bloqueio proprietário do Google Analytics.
• **Privacidade**: Controle os dados com instâncias auto-hospedadas; o Google Analytics compartilha dados com o Google.
• **Tudo em Um**: Análises, replay de sessão, feature flags e experimentos em uma única plataforma, em vez das ferramentas fragmentadas do Google.
• **Automação**: O **PostHog MCP Server** permite consultas em linguagem natural, ao contrário dos painéis manuais do Google Analytics.
• **Comunidade**: Mais de 1.500 estrelas no GitHub e suporte ativo, rivalizando com o Google, mas com flexibilidade de código aberto.

Mudei um projeto paralelo para o PostHog e adorei a privacidade e o controle de feature flags — sem o inchaço do Google Analytics!

Personalizando e Estendendo o PostHog MCP Server

Eleve o nível da sua configuração:

• **Ferramentas Personalizadas**: Adicione novas ferramentas ao servidor (por exemplo, insights SQL personalizados) via github.com/PostHog/mcp.
• **Múltiplos Projetos**: Consulte todos os projetos com “Listar todos os projetos na minha organização PostHog.”
• **Feature Flags**: Gere código para alternar flags:

Generate a Python snippet to toggle feature flag 'new-ui' in project 12345
using the PostHog MCP Server.

• **Contribuir**: Envie PRs para aprimorar o servidor — o PostHog os recebe de bom grado.

Por que o PostHog MCP Server é Essencial para Desenvolvedores

O **PostHog MCP Server** faz a automação de análises parecer uma conversa com um guru de dados. Sua interface de linguagem natural e a vantagem de código aberto do PostHog superam o Google Analytics para equipes preocupadas com a privacidade. A configuração pode ser complicada (problemas com a chave de API!), mas a documentação do PostHog e a comunidade são salva-vidas.

Pronto para usar o **PostHog MCP Server**? Inicie o Cline ou Cursor, consulte esses insights e compartilhe suas vitórias em análises — estou animado para ver sua configuração brilhar!