Beehiiv MCP Server

A Model Context Protocol (MCP) server for Beehiiv. Connect your Beehiiv newsletter to Claude Desktop and manage subscribers, posts, segments, webhooks, automations, and more using natural language.

Built by Shane Brady.

Requirements

• Node.js v18 or higher
• Claude Desktop
• A Beehiiv account with API access

Installation

1. Open a terminal

• Mac: Open Terminal (search "Terminal" in Spotlight, or find it in Applications → Utilities)
• Windows: Open PowerShell (search "PowerShell" in the Start menu)

2. Clone and install

git clone https://github.com/shanebrady77/beehiivmcp.git
cd beehiivmcp
npm install

Configuration

Open your Claude Desktop config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "beehiiv": {
      "command": "node",
      "args": ["/absolute/path/to/beehiivmcp/server.js"],
      "env": {
        "BEEHIIV_API_KEY": "your_api_key_here",
        "BEEHIIV_PUB_ID": "pub_xxxxxxxxxx"
      }
    }
  }
}

Important: Use the full absolute path to server.js. Example on Mac: /Users/yourname/Documents/beehiivmcp/server.js

Restart Claude Desktop after saving.

Finding Your Beehiiv Credentials

• API Key: Beehiiv dashboard → Settings → Integrations → API → Generate key
• Publication ID: Settings → General — looks like pub_xxxxxxxxxxxx

Tools

Tools are grouped by prefix so Claude can quickly identify the right one.

publication_ — Stats

• publication_get_stats — Total subscribers, open rates, click rates

subscriber_ — Subscriber management

• subscriber_list — List with status filter and pagination
• subscriber_get — Look up by email
• subscriber_get_rich — Full detail with stats, referrals, custom fields
• subscriber_list_filtered — Filter by status, tier, date range
• subscriber_add — Add or reactivate with custom fields and UTM params
• subscriber_update — Change tier, custom fields, or unsubscribe
• subscriber_delete — Permanently delete
• subscriber_tag — Tag up to 50 subscribers by email
• subscriber_bulk_add — Import a list at once
• subscriber_bulk_update — Update up to 1000 at once

post_ — Newsletter posts

• post_list — List posts with stats
• post_get — Full post details and performance
• post_create — Create a draft or scheduled post
• post_update — Edit subject, preview text, status, or schedule
• post_delete — Delete a draft
• post_analytics — Performance trends across recent posts

segment_ — Segments

• segment_list — List all segments
• segment_get — Segment details and member count

automation_ — Automations

• automation_list — List automations by status
• automation_get — Automation details and steps

webhook_ — Webhooks

• webhook_list — List all webhooks
• webhook_get — Get a specific webhook
• webhook_create — Create webhook (14 event types supported)
• webhook_update — Update event types or description
• webhook_delete — Remove a webhook

referral_ — Referral program

• referral_program_get — Referral program details and milestones
• referral_leaderboard — Top referrers ranked by referral count

settings_ — Publication settings

• settings_list_custom_fields — See all custom field definitions
• settings_list_tiers — List free and premium tiers
• settings_list_ad_opportunities — View ad placements with payout rates

troubleshoot — Setup validation

• troubleshoot — Check API key, publication ID, and connectivity

Example Prompts

Once installed, try asking Claude:

• "Show me my subscriber count and open rates"
• "How have my last 10 posts performed?"
• "Add [email protected] as a subscriber"
• "Who are my top referrers?"
• "Tag all subscribers who signed up this month with 'march-2026'"
• "Draft a post with the subject 'Weekly Roundup' and a paragraph about our latest feature"
• "Show me all my automations"
• "Something's not working — run troubleshoot"

Updating

cd beehiivmcp
git pull

Then restart Claude Desktop. No config changes needed — your API key and publication ID stay the same.

Security & Privacy

Your API key never leaves your computer.

Here's exactly what's happening when you set this up:

• The server.js file runs locally on your machine — it's not a website, not a cloud service, not a server somewhere on the internet. It's just a program running in the background on your computer, the same way Spotify or Dropbox runs in the background.

• Your Beehiiv API key lives in the Claude Desktop config file on your hard drive. It's never uploaded anywhere, never sent to GitHub, and never shared with anyone. It's read-only by your local machine.

• When you ask Claude something like "show me my subscribers", Claude talks to the local server running on your computer, which then makes a request to Beehiiv's API using your key, and returns the result. That's the whole chain — Claude → your computer → Beehiiv → back to you.

• The API key itself is like a password that only has the permissions you've given it in Beehiiv. If you're worried, you can create a read-only API key in Beehiiv settings so it can never make changes — only look things up.

What this server can and can't do:

• It can only do what Beehiiv's API allows — it can't access anything outside your Beehiiv account
• It creates posts as drafts only — it can never send a newsletter without you manually pressing send in the Beehiiv dashboard
• It has no access to your email, your computer files, or anything else

The one thing to be careful about: don't share your Claude Desktop config file with anyone, since it contains your API key in plain text. Treat it like you'd treat a file with a password in it.

License

MIT