Beehiiv

Gerencie sua newsletter Beehiiv adicionando assinantes e buscando posts usando linguagem natural.

Documentação

Servidor MCP Beehiiv

🚀 Início Rápido: Configure o gerenciamento de newsletters Beehiiv no Claude Desktop em menos de 2 minutos - sem necessidade de Java!

Conecte sua newsletter Beehiiv ao Claude Desktop e outros assistentes de IA. Adicione assinantes, busque posts e gerencie publicações usando linguagem natural.

🎯 Escolha Seu Método de Configuração

Método	Tempo	Requisitos	Melhor Para
📦 Binário Nativo	2 min	Nenhum!	A maioria dos usuários
☕ Build Java	5 min	Java 24+	Desenvolvedores

O Que Você Pode Fazer

Após a configuração, você pode pedir ao Claude Desktop coisas como:

"Adicione test@example.com à minha newsletter"
"Mostre meus últimos 5 posts da newsletter"
"Crie um assinante com campos personalizados: nome João, empresa Tech Corp"
"Liste todas as minhas publicações"

📦 Binário Nativo (Sem Java)

Perfeito para a maioria dos usuários - Download de um único arquivo, sem necessidade de instalação!

1. Obtenha Suas Credenciais de API

Acesse Configurações de API do Beehiiv
Copie sua Chave de API (começa com bh-)
Copie seu ID de Publicação (começa com pub_)

2. Baixe o Binário

Opção A: Instalação com Um Comando (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/danvega/beehiiv-mcp-server/main/scripts/install.sh | bash

Opção B: Download Manual

Acesse Última Versão e baixe:

Linux: beehiiv-mcp-server-linux
macOS: beehiiv-mcp-server-macos
Windows: beehiiv-mcp-server-windows.exe

Torne executável (apenas Linux/macOS):

chmod +x beehiiv-mcp-server-*

3. Configure o Claude Desktop

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

{
  "mcpServers": {
    "beehiiv": {
      "command": "/full/path/to/beehiiv-mcp-server-linux",
      "env": {
        "BEEHIIV_API": "bh-your-api-key-here",
        "BEEHIIV_PUBLICATION_ID": "pub-your-publication-id-here"
      }
    }
  }
}

⚠️ Use o caminho completo para o arquivo binário baixado.

4. Teste se Funciona

Reinicie o Claude Desktop
Procure pelo ícone 🔧 em uma nova conversa
Tente: "Adicione assinante test@example.com à minha newsletter"

✅ Sucesso: Você deve ver o Claude usar a ferramenta beehiiv_create_subscription!

☕ Build Java (Tradicional)

Para desenvolvedores que desejam compilar a partir do código-fonte

Pré-requisitos

Java 21+ (Baixe aqui)
Maven (incluído via ./mvnw)

Passos

git clone <this-repo>
cd beehiiv-mcp-server
./mvnw clean package -DskipTests

Depois configure o Claude Desktop com:

{
  "mcpServers": {
    "beehiiv": {
      "command": "java",
      "args": [
        "-jar", 
        "/FULL/PATH/TO/target/beehiiv-mcp-server-0.0.3-SNAPSHOT.jar"
      ],
      "env": {
        "BEEHIIV_API": "bh-your-api-key-here",
        "BEEHIIV_PUBLICATION_ID": "pub-your-publication-id-here"
      }
    }
  }
}

🔥 Build de Imagem Nativa (Avançado)

Para desenvolvedores que desejam criar binários nativos otimizados

A compilação de imagem nativa cria executáveis de inicialização rápida e baixo consumo de memória que não requerem Java para executar.

Pré-requisitos

Java 21+ com GraalVM (Baixe o GraalVM)
Maven (incluído via ./mvnw)

Build da Imagem Nativa

git clone <this-repo>
cd beehiiv-mcp-server
./mvnw clean package -Pnative -DskipTests

Isso cria binários específicos da plataforma em target/:

Linux: beehiiv-mcp-server-linux
macOS: beehiiv-mcp-server-macos
Windows: beehiiv-mcp-server-windows.exe

Configure o Claude Desktop

Use o binário nativo diretamente sem Java:

{
  "mcpServers": {
    "beehiiv": {
      "command": "/full/path/to/beehiiv-mcp-server-linux",
      "env": {
        "BEEHIIV_API": "bh-your-api-key-here",
        "BEEHIIV_PUBLICATION_ID": "pub-your-publication-id-here"
      }
    }
  }
}

Benefícios

Inicialização rápida: ~50ms vs ~2s para Java
Baixo consumo de memória: ~20MB vs ~100MB para Java
Sem necessidade de Java: Executável autossuficiente
Melhor para produção: Desempenho otimizado em tempo de execução

Pré-requisitos

Java 21+ (Baixe aqui)
Maven (incluído via ./mvnw)
Conta Beehiiv com acesso à API
Claude Desktop (Baixe aqui)

Ferramentas Disponíveis

📧 Gerenciamento de Assinaturas

Adicionar assinantes: Crie novas assinaturas com campos personalizados
Encontrar assinantes: Pesquise por e-mail ou ID
Campos personalizados: Adicione dados estruturados aos assinantes

📝 Gerenciamento de Conteúdo

Obter posts: Busque suas newsletters publicadas
Post individual: Obtenha conteúdo detalhado de posts específicos
Filtragem: Pesquise por tags, data, tipo de público

🏢 Gerenciamento de Publicações

Listar publicações: Veja todas as suas newsletters
Detalhes da publicação: Obtenha estatísticas e configurações
Multi-publicação: Trabalhe com várias newsletters

Exemplo de Uso

Assinante Básico

Add john.doe@company.com to my newsletter

Assinante com Dados Personalizados

Create a subscription for sarah@startup.com with custom fields: 
name "Sarah Johnson", role "CEO", company "TechStart"

Obter Posts Recentes

Show me my last 10 newsletter posts with their titles and publish dates

Rastreamento UTM

Add marketing@bigcorp.com with UTM source "website", 
medium "signup", campaign "q4-growth"

Configuração Avançada

Múltiplas Publicações

Não defina BEEHIIV_PUBLICATION_ID para trabalhar com várias newsletters:

{
  "env": {
    "BEEHIIV_API": "bh-your-api-key-here"
  }
}

Depois especifique a publicação em suas solicitações:

Add user@example.com to publication pub_specific123

Modo HTTP (Alternativo)

Para testes ou desenvolvimento, você pode executar como servidor web:

java -jar target/beehiiv-mcp-server-0.0.2-SNAPSHOT.jar

Depois use: "httpUrl": "http://localhost:8080/mcp" na configuração do Claude Desktop.

Solução de Problemas

"Ferramenta não encontrada" no Claude Desktop

Verifique se o caminho do JAR está correto e é absoluto
Verifique se as variáveis de ambiente estão definidas
Reinicie o Claude Desktop completamente
Verifique os logs/console do Claude Desktop para erros

Erros de "Chave de API inválida"

Verifique se sua chave de API começa com bh-
Verifique se foi copiada completamente (sem espaços extras)
Certifique-se de que sua conta Beehiiv tem acesso à API habilitado

"Publicação não encontrada"

Verifique se seu ID de Publicação começa com pub_
Verifique se você tem acesso a esta publicação
Tente sem BEEHIIV_PUBLICATION_ID e especifique por solicitação

Ativar Logs de Depuração

Defina a variável de ambiente: LOGGING_LEVEL_ROOT=DEBUG

Testar Conexão Manualmente

# Test the server directly
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list"}'

Desenvolvimento

Executar Testes

./mvnw test

Compilar a partir do Código-Fonte

./mvnw clean package

Estrutura do Projeto

src/main/java/dev/danvega/beehiiv/
├── Application.java              # Main Spring Boot app
├── core/                        # Configuration & utilities
├── post/                        # Newsletter post management
├── publication/                 # Publication management  
└── subscription/                # Subscriber management

Referência da API

Para documentação detalhada da API Beehiiv: developers.beehiiv.com

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para novas funcionalidades
Envie um pull request

Suporte

Issues: Issues do GitHub
API Beehiiv: Documentação Oficial
Protocolo MCP: Model Context Protocol