🚀 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.

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

• "Add [email protected] 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"

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

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

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-*

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.

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

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

For developers who want to build from source

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

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

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.

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

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

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

• 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

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

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

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

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

Add [email protected] to my newsletter

Create a subscription for [email protected] with custom fields: 
name "Sarah Johnson", role "CEO", company "TechStart"

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

Add [email protected] with UTM source "website", 
medium "signup", campaign "q4-growth"

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 [email protected] to publication pub_specific123

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.

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

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

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

Set environment variable: LOGGING_LEVEL_ROOT=DEBUG

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

./mvnw test

./mvnw clean package

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

For detailed Beehiiv API documentation: developers.beehiiv.com

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

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