Beehiiv

Gestiona tu boletín de Beehiiv añadiendo suscriptores y obteniendo publicaciones usando lenguaje natural.

Documentación

Servidor MCP de Beehiiv

🚀 Inicio súper rápido: Consigue que la gestión de boletines de Beehiiv funcione en Claude Desktop en menos de 2 minutos - ¡sin necesidad de Java!

Conecta tu boletín de Beehiiv a Claude Desktop y otros asistentes de IA. Añade suscriptores, obtén publicaciones y gestiona publicaciones usando lenguaje natural.

🎯 Elige tu método de configuración

Método	Tiempo	Requisitos	Mejor para
📦 Binario Nativo	2 min	¡Ninguno!	La mayoría de usuarios
☕ Compilación Java	5 min	Java 24+	Desarrolladores

Lo que puedes hacer

Una vez configurado, puedes pedirle a Claude Desktop cosas como:

"Añade test@example.com a mi boletín"
"Muéstrame mis últimas 5 publicaciones del boletín"
"Crea un suscriptor con campos personalizados: nombre John, empresa Tech Corp"
"Lista todas mis publicaciones"

📦 Binario Nativo (Sin Java)

Perfecto para la mayoría de usuarios - Descarga de un solo archivo, ¡sin instalación requerida!

1. Obtén tus credenciales de API

Ve a Configuración de API de Beehiiv
Copia tu Clave de API (comienza con bh-)
Copia tu ID de Publicación (comienza con pub_)

2. Descargar el binario

Opción A: Instalación con un comando (Linux/macOS)

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

Opción B: Descarga manual

Ve a Última versión y descarga:

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

Hazlo ejecutable (solo Linux/macOS):

chmod +x beehiiv-mcp-server-*

3. Configura 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"
      }
    }
  }
}

⚠️ Usa la ruta completa a tu archivo binario descargado.

4. Prueba que funciona

Reinicia Claude Desktop
Busca el icono 🔧 en una nueva conversación
Prueba: "Añade suscriptor test@example.com a mi boletín"

✅ Éxito: Deberías ver a Claude usar la herramienta beehiiv_create_subscription!

☕ Compilación Java (Tradicional)

Para desarrolladores que quieren compilar desde el código fuente

Requisitos previos

Java 21+ (Descargar aquí)
Maven (incluido mediante ./mvnw)

Pasos

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

Luego configura Claude Desktop con:

{
  "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"
      }
    }
  }
}

🔥 Compilación de Imagen Nativa (Avanzado)

Para desarrolladores que quieren crear binarios nativos optimizados

La compilación de imagen nativa crea ejecutables de inicio rápido y bajo consumo de memoria que no requieren Java para ejecutarse.

Requisitos previos

Java 21+ con GraalVM (Descargar GraalVM)
Maven (incluido mediante ./mvnw)

Compilar imagen nativa

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

Esto crea binarios específicos de plataforma en target/:

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

Configura Claude Desktop

Usa el binario nativo directamente sin 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"
      }
    }
  }
}

Beneficios

Inicio rápido: ~50ms vs ~2s para Java
Bajo consumo de memoria: ~20MB vs ~100MB para Java
Sin necesidad de Java: Ejecutable autocontenido
Mejor para producción: Rendimiento optimizado en tiempo de ejecución

Requisitos previos

Java 21+ (Descargar aquí)
Maven (incluido mediante ./mvnw)
Cuenta de Beehiiv con acceso a API
Claude Desktop (Descargar aquí)

Herramientas disponibles

📧 Gestión de suscripciones

Añadir suscriptores: Crea nuevas suscripciones con campos personalizados
Buscar suscriptores: Busca por correo electrónico o ID
Campos personalizados: Añade datos estructurados a los suscriptores

📝 Gestión de contenido

Obtener publicaciones: Obtén tus boletines publicados
Publicación individual: Obtén contenido detallado para publicaciones específicas
Filtrado: Busca por etiquetas, fecha, tipo de audiencia

🏢 Gestión de publicaciones

Listar publicaciones: Ve todos tus boletines
Detalles de publicación: Obtén estadísticas y configuraciones
Multi-publicación: Trabaja con múltiples boletines

Ejemplo de uso

Suscriptor básico

Add john.doe@company.com to my newsletter

Suscriptor con datos personalizados

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

Obtener publicaciones recientes

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

Seguimiento UTM

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

Configuración avanzada

Múltiples publicaciones

No establezcas BEEHIIV_PUBLICATION_ID para trabajar con múltiples boletines:

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

Luego especifica la publicación en tus solicitudes:

Add user@example.com to publication pub_specific123

Modo HTTP (Alternativa)

Para pruebas o desarrollo, puedes ejecutarlo como servidor web:

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

Luego usa: "httpUrl": "http://localhost:8080/mcp" en la configuración de Claude Desktop.

Solución de problemas

"Herramienta no encontrada" en Claude Desktop

Verifica que la ruta del JAR sea correcta y absoluta
Verifica que las variables de entorno estén configuradas
Reinicia Claude Desktop por completo
Revisa los registros/consola de Claude Desktop para ver errores

Errores de "Clave de API inválida"

Verifica que tu clave de API comience con bh-
Verifica que esté copiada completamente (sin espacios extra)
Asegúrate de que tu cuenta de Beehiiv tenga habilitado el acceso a API

"Publicación no encontrada"

Verifica que tu ID de Publicación comience con pub_
Verifica que tengas acceso a esta publicación
Prueba sin BEEHIIV_PUBLICATION_ID y especifícalo por solicitud

Habilitar registro de depuración

Establece la variable de entorno: LOGGING_LEVEL_ROOT=DEBUG

Probar conexión 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"}'

Desarrollo

Ejecutar pruebas

./mvnw test

Compilar desde el código fuente

./mvnw clean package

Estructura del proyecto

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

Referencia de API

Para documentación detallada de la API de Beehiiv: developers.beehiiv.com

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Añade pruebas para la nueva funcionalidad
Envía una solicitud de extracción (pull request)

Soporte

Problemas: Issues de GitHub
API de Beehiiv: Documentación oficial
Protocolo MCP: Model Context Protocol