Beehiiv 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