danvega/beehiiv-mcp-server

Beehiiv MCP Server

🚀 Super Quick Start: Get Beehiiv newsletter management working in Claude Desktop in under 2 minutes - no Java required!

Connect your Beehiiv newsletter to Claude Desktop and other AI assistants. Add subscribers, fetch posts, and manage publications using natural language.

🎯 Choose Your Setup Method

What You Can Do

Once set up, you can ask Claude Desktop things like:

• "Add to my newsletter"
• "Show me my latest 5 newsletter posts"
• "Create a subscriber with custom fields: name John, company Tech Corp"
• "List all my publications"

📦 Native Binary (No Java)

Perfect for most users - Single file download, no installation required!

1. Get Your API Credentials

1. Go to Beehiiv API Settings
2. Copy your API Key (starts with bh-)
3. Copy your Publication ID (starts with pub_)

2. Download Binary

Option A: One-Command Install (Linux/macOS)

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

Option B: Manual Download

Go to Latest Release and download:

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

Make executable (Linux/macOS only):

chmod +x beehiiv-mcp-server-*

3. Configure 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 the full path to your downloaded binary file.

4. Test It Works

1. Restart Claude Desktop
2. Look for the 🔧 icon in a new conversation
3. Try: "Add subscriber to my newsletter"

✅ Success: You should see Claude use the beehiiv_create_subscription tool!

☕ Java Build (Traditional)

For developers who want to build from source

Prerequisites

• Java 21+ (Download here)
• Maven (included via ./mvnw)

Steps

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

Then configure Claude Desktop with:

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

🔥 Native Image Build (Advanced)

For developers who want to create optimized native binaries

Native image compilation creates fast-starting, low-memory executables that don't require Java to run.

Prerequisites

• Java 21+ with GraalVM (Download GraalVM)
• Maven (included via ./mvnw)

Build Native Image

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

This creates platform-specific binaries in target/:

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

Configure Claude Desktop

Use the native binary directly without 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"
      }
    }
  }
}

Benefits

• Fast startup: ~50ms vs ~2s for Java
• Low memory: ~20MB vs ~100MB for Java
• No Java required: Self-contained executable
• Better for production: Optimized runtime performance

Prerequisites

• Java 21+ (Download here)
• Maven (included via ./mvnw)
• Beehiiv account with API access
• Claude Desktop (Download here)

Available Tools

📧 Subscription Management

• Add subscribers: Create new subscriptions with custom fields
• Find subscribers: Look up by email or ID
• Custom fields: Add structured data to subscribers

📝 Content Management

• Get posts: Fetch your published newsletters
• Single post: Get detailed content for specific posts
• Filtering: Search by tags, date, audience type

🏢 Publication Management

• List publications: See all your newsletters
• Publication details: Get stats and settings
• Multi-publication: Work with multiple newsletters

Example Usage

Basic Subscriber

Add john.doe@company.com to my newsletter

Subscriber with Custom Data

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

Get Recent Posts

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

UTM Tracking

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

Advanced Configuration

Multiple Publications

Don't set BEEHIIV_PUBLICATION_ID to work with multiple newsletters:

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

Then specify the publication in your requests:

Add user@example.com to publication pub_specific123

HTTP Mode (Alternative)

For testing or development, you can run as a web server:

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

Then use: "httpUrl": "http://localhost:8080/mcp" in Claude Desktop config.

Troubleshooting

"Tool not found" in Claude Desktop

1. Check the JAR path is correct and absolute
2. Verify environment variables are set
3. Restart Claude Desktop completely
4. Check Claude Desktop's logs/console for errors

"Invalid API key" errors

1. Verify your API key starts with bh-
2. Check it's copied completely (no extra spaces)
3. Ensure your Beehiiv account has API access enabled

"Publication not found"

1. Verify your Publication ID starts with pub_
2. Check you have access to this publication
3. Try without BEEHIIV_PUBLICATION_ID and specify it per request

Enable Debug Logging

Set environment variable: LOGGING_LEVEL_ROOT=DEBUG

Test Connection Manually

# 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"}'

Development

Run Tests

./mvnw test

Build from Source

./mvnw clean package

Project Structure

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

API Reference

For detailed Beehiiv API documentation: developers.beehiiv.com

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Support

• Issues: GitHub Issues
• Beehiiv API: Official Documentation
• MCP Protocol: Model Context Protocol