A comprehensive Model Context Protocol server for the beehiiv newsletter platform API v2.
Provides 34 tools covering the full beehiiv API — publications, subscriptions, posts, segments, automations, webhooks, custom fields, referral programs, tags, and bulk operations — enabling Claude to manage your newsletter through natural conversation.
- What Is This?
- Prerequisites
- Installation
- Setting Up a Newsletter Manager Project
- Getting Your beehiiv Credentials
- Environment Variables
- Available Tools
- Usage Examples
- Security
- Architecture
- Development
- Troubleshooting
- API Coverage
- License
This MCP server acts as a bridge between Claude (via Claude Desktop or Claude Code) and the beehiiv newsletter platform. Once installed, you can manage your entire newsletter operation through natural language — ask Claude to check your subscriber count, create posts, manage tags, view automation stats, and much more.
Think of it as giving Claude direct access to your beehiiv dashboard, so instead of clicking through menus, you just tell Claude what you need.
- Node.js v18 or later
- A beehiiv account with API access
- Claude Desktop and/or Claude Code
This is the easiest way to get started. Claude Desktop is a free app that runs on macOS and Windows.
- Visit claude.ai/download
- Download the installer for your operating system (macOS or Windows)
- Run the installer and sign in with your Anthropic account
Open your terminal (Terminal on macOS, PowerShell on Windows) and run:
git clone https://github.com/mrhinkle/beehiiv-mcp-server.git
cd beehiiv-mcp-server
npm install
npm run buildNote the full path to the cloned directory — you'll need it in the next step. You can find it by running:
pwdThis will output something like /Users/yourname/beehiiv-mcp-server.
Edit the Claude Desktop config file:
macOS:
nano ~/Library/Application\ Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the following (or merge with any existing config). Replace the placeholder paths and credentials:
{
"mcpServers": {
"beehiiv": {
"command": "node",
"args": ["/Users/yourname/beehiiv-mcp-server/build/index.js"],
"env": {
"BEEHIIV_API_KEY": "bh-your-api-key-here",
"BEEHIIV_PUBLICATION_ID": "pub_your-publication-id-here"
}
}
}
}Important: Use the absolute path from Step 2. On Windows, use forward slashes or escaped backslashes:
C:/Users/yourname/beehiiv-mcp-server/build/index.js
Quit Claude Desktop completely (don't just close the window) and reopen it. You should see the beehiiv tools appear via the hammer (🔨) icon in the chat input area.
If you see a red or disconnected indicator, check Troubleshooting.
Claude Code is a CLI tool for developers. Add the beehiiv MCP server to your settings:
nano ~/.claude/settings.jsonAdd or merge:
{
"mcpServers": {
"beehiiv": {
"command": "node",
"args": ["/absolute/path/to/beehiiv-mcp-server/build/index.js"],
"env": {
"BEEHIIV_API_KEY": "bh-your-api-key-here",
"BEEHIIV_PUBLICATION_ID": "pub_your-publication-id-here"
}
}
}
}Alternatively, add the same mcpServers block to .claude/settings.json in your project directory for project-scoped access.
Start a new Claude Code session to pick up the changes.
For the best experience, create a dedicated Claude Desktop Project for your newsletter management. This lets you customize Claude's behavior and add skills as you discover workflows.
- Open Claude Desktop
- Click on the Projects tab in the sidebar
- Click Create Project
- Name it something like "My Newsletter Manager" or "[Newsletter Name] Dashboard"
- In the project instructions, add context about your newsletter:
You are my beehiiv newsletter manager. My newsletter is called "[Your Newsletter Name]"
and focuses on [your topic].
When I ask about subscribers, posts, or stats, use the beehiiv MCP tools.
Some common things I do:
- Check subscriber growth weekly
- Review post performance after each send
- Tag new subscribers based on signup source
- Monitor automation journey completions
As you work with the newsletter manager, you'll discover common workflows. Here are some ideas to add as project skills:
Weekly Newsletter Review Prompt:
"Give me a weekly summary: total subscribers, new subscribers this week, most recent post stats, and any active automations."
Subscriber Segmentation Prompt:
"Show me all available segments and their subscriber counts, then list the tags I have set up."
Post Performance Prompt:
"Get the aggregate stats for my posts from the last 30 days — total sends, opens, clicks, and unsubscribes."
New Subscriber Onboarding Check:
"Look up the subscriber with email [email] and show me their full profile including tags, custom fields, and automation journey status."
The project-based approach lets you build a personalized newsletter management assistant over time, adding instructions and prompt shortcuts as you learn what works best for your workflow.
You need two credentials to use this MCP server:
- Log in to your beehiiv Dashboard
- Go to Settings → Integrations → API
- Click Create New API Key
- Copy the key immediately — it starts with
bh-and is only shown once - Store it securely (e.g., a password manager)
Plan requirements: API access is available on beehiiv's Scale and Enterprise plans. Some tools (webhooks, post creation) may require higher-tier plans.
Your Publication ID appears in your beehiiv dashboard URL:
https://app.beehiiv.com/publications/pub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is your Publication ID
Alternatively, after setting up the MCP server with just your API key, you can ask Claude to run list_publications to find it.
| Variable | Required | Format | Description |
|---|---|---|---|
BEEHIIV_API_KEY |
Yes | bh-... |
beehiiv API key from the Integrations settings |
BEEHIIV_PUBLICATION_ID |
Yes | pub_... |
Publication ID from your dashboard URL |
Both are validated at startup — the server will not start if they are missing or malformed.
| Tool | Description |
|---|---|
list_publications |
List all publications accessible with your API key |
get_publication |
Get publication details with optional stats (total subscribers, active subscribers, etc.) |
| Tool | Description |
|---|---|
list_subscriptions |
List/filter subscriptions by status, tier, email, creation date. Supports pagination. |
get_subscription |
Get a subscription by ID with expand options (stats, custom fields, tags, referrals) |
get_subscription_by_email |
Look up a subscription by email address |
create_subscription |
Create a new subscriber with optional UTMs, custom fields, referral codes, and automation enrollment |
update_subscription |
Update subscriber tier, email, custom fields, or unsubscribe status |
delete_subscription |
Permanently delete a subscription |
| Tool | Description |
|---|---|
list_posts |
List posts with filters: status (draft, confirmed, archived), audience, platform, content tags |
get_post |
Get post details with expand options for content and/or statistics |
create_post |
Create a new post with HTML content (Enterprise plan required) |
delete_post |
Delete a post |
get_post_aggregate_stats |
Get aggregate statistics across all posts (opens, clicks, unsubscribes, etc.) |
| Tool | Description |
|---|---|
list_segments |
List all audience segments |
get_segment |
Get segment details with optional stats expand |
delete_segment |
Delete a segment |
get_segment_results |
Get the list of subscriptions that belong to a segment |
| Tool | Description |
|---|---|
list_automations |
List all automations (sequences, workflows) |
get_automation |
Get automation details including steps and performance stats |
| Tool | Description |
|---|---|
create_automation_journey |
Enroll a subscriber into an automation sequence |
get_automation_journey |
Check a subscriber's journey status within an automation |
| Tool | Description |
|---|---|
list_custom_fields |
List all custom field definitions for the publication |
get_custom_field |
Get a single custom field definition by ID |
delete_custom_field |
Delete a custom field (removes it from all subscriptions) |
| Tool | Description |
|---|---|
list_webhooks |
List all webhooks (Scale plan required) |
get_webhook |
Get a webhook by ID |
create_webhook |
Create a webhook with event type subscriptions (SSRF protection enforced) |
delete_webhook |
Delete a webhook |
Supported webhook event types: post.sent, post.updated, subscription.confirmed, subscription.created, subscription.downgraded, subscription.paused, subscription.resumed, subscription.upgraded, subscription.deleted, subscription.tier.paused, subscription.tier.resumed, subscription.tier.created, subscription.tier.deleted, survey.response_submitted
| Tool | Description |
|---|---|
get_referral_program |
Get referral program configuration, milestones, and rewards |
| Tool | Description |
|---|---|
list_subscription_tags |
List all subscription tags |
create_subscription_tag |
Create a new tag |
delete_subscription_tag |
Delete a tag by ID |
| Tool | Description |
|---|---|
bulk_create_subscriptions |
Create up to 1,000 subscriptions in a single request |
bulk_update_subscriptions |
Update up to 1,000 subscriptions in a single request |
Here are common things you can ask Claude once the server is configured:
"How many active subscribers do I have?"
"Look up the subscriber john@example.com"
"Create a new subscriber with email jane@example.com and tag them as 'VIP'"
"Show me all subscribers who signed up this month"
"What custom fields do I have set up?"
"What are my aggregate post stats for the last 30 days?"
"Show me my most recent published posts"
"Get the full stats for my latest post including opens, clicks, and unsubscribes"
"List all my draft posts"
"List all my audience segments and their sizes"
"Show me the subscribers in my 'Engaged Readers' segment"
"Create a new tag called 'Webinar Attendees'"
"What tags do I currently have?"
"List all my automations and their status"
"Enroll subscriber sub_xxx into automation aut_yyy"
"Check the journey status for subscriber sub_xxx in automation aut_yyy"
"List my active webhooks"
"Create a webhook to https://my-app.com/webhook that fires on subscription.created and post.sent"
"Delete the webhook with ID wh_xxx"
"Show me my referral program milestones and rewards"
"Import these 5 subscribers: alice@example.com, bob@example.com, carol@example.com, dave@example.com, eve@example.com"
"Update all these subscribers to premium tier: [list of subscription IDs]"
This server implements multiple layers of security hardening:
- Path traversal prevention — All resource IDs (subscription IDs, post IDs, webhook IDs, etc.) are validated to block
../,%2F,%2E, null bytes, and other traversal patterns before being interpolated into API URLs. - String length limits — Free-form text inputs (tag names, descriptions, etc.) are length-checked to prevent oversized payloads.
- HTML content validation — Post body content is validated for length to prevent context-window flooding.
- Webhook URL validation — Webhook URLs are checked against SSRF patterns: blocks private IPs (
10.x,172.16-31.x,192.168.x), localhost, cloud metadata endpoints (169.254.169.254), and requires HTTPS.
- HTTPS-only — The base URL is pinned to
https://api.beehiiv.com/v2; no HTTP fallback is possible. - Response size limits — Response bodies are capped at 5 MB via streaming reads to prevent memory exhaustion.
- Request timeouts — All API calls timeout after 30 seconds via
AbortSignal.timeout. - Error sanitization — API error bodies are scrubbed of Bearer tokens and API keys before being returned to tool output.
- Error truncation — Error messages are capped at 2,000 characters to prevent context-window flooding.
- Rate limit awareness — HTTP 429 responses return a friendly retry message instead of raw error data.
- No source maps — TypeScript source maps are disabled in production builds.
- Gitignore hardening —
.envfiles, logs, editor configs, and OS metadata files are excluded from version control. - Startup validation — API key and publication ID formats are validated at server startup (key length, prefix format, no whitespace) so misconfigurations fail fast with clear error messages.
src/
├── index.ts # Entry point — env validation, server setup, transport
├── lib/
│ ├── api-client.ts # Centralized HTTP client with security hardening
│ ├── types.ts # TypeScript interfaces for all beehiiv data models
│ └── sanitize.ts # Input validation and security utilities
└── tools/
├── publications.ts # 2 tools — list and get publications
├── subscriptions.ts # 6 tools — full subscription CRUD
├── posts.ts # 5 tools — post management and stats
├── segments.ts # 4 tools — segment queries and management
├── automations.ts # 2 tools — list and get automations
├── automation-journeys.ts # 2 tools — journey enrollment and status
├── custom-fields.ts # 3 tools — custom field management
├── webhooks.ts # 4 tools — webhook CRUD with SSRF protection
├── referral-program.ts # 1 tool — referral program details
├── subscription-tags.ts # 3 tools — tag management
└── bulk-subscriptions.ts # 2 tools — batch create/update
- Modular tool registration — Each tool group is a separate file that exports a
register*Tools()function. This makes it easy to add new API coverage or remove unused tools. - Centralized HTTP client — All API communication goes through
ApiClient, ensuring consistent auth, timeouts, error handling, and security across all tools. - Defense in depth — Input validation happens at both the Zod schema level (type checking, enum constraints) and the sanitization level (path traversal, SSRF, length limits).
- Fail-fast startup — Credential issues are caught at server startup, not on the first API call.
# Install dependencies
npm install
# Run in development mode (no build needed, uses tsx)
npm run dev
# Build TypeScript to JavaScript
npm run build
# Run the built version
npm startYou can test the server interactively using the MCP Inspector:
npx @modelcontextprotocol/inspector node build/index.jsThis opens a web UI where you can browse tools, invoke them, and inspect responses.
- Create a new file in
src/tools/(or add to an existing one) - Export a
registerXxxTools(server, client)function - Use
server.registerTool()with Zod schemas for input validation - Call
validateResourceId()on any user-provided IDs before URL interpolation - Import and call your registration function in
src/index.ts - Rebuild with
npm run build
- Make sure you fully quit Claude Desktop (not just closed the window) and reopened it
- Check that the path in your config is an absolute path to
build/index.js - Verify the server builds without errors:
cd beehiiv-mcp-server && npm run build - Check the Claude Desktop logs for MCP errors
- Your API key may be expired or invalid
- Generate a new key at: beehiiv Dashboard → Settings → Integrations → API
- Make sure the key starts with
bh-and has no extra whitespace
- Some endpoints require higher beehiiv plans:
- Webhooks require the Scale plan or above
- Post creation requires the Enterprise plan
- Check your plan at: beehiiv Dashboard → Settings → Billing
- Verify the ID you're using is correct and belongs to your publication
- IDs typically look like
sub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- beehiiv limits API requests per minute
- Wait 60 seconds and try again
- Avoid rapid successive calls (e.g., looping through large lists)
- The API key must start with
bh-, be at least 10 characters, and contain no whitespace - Copy the key directly from beehiiv — don't add quotes or spaces
- The publication ID must start with
pub_and contain no whitespace - Find it in your beehiiv dashboard URL or run
list_publicationsafter setting the API key
This server provides complete coverage of the beehiiv API v2:
| API Resource | Endpoints Covered | Plan Required |
|---|---|---|
| Publications | List, Get | All with API access |
| Subscriptions | List, Get, Get by Email, Create, Update, Delete | All with API access |
| Posts | List, Get, Create, Delete, Aggregate Stats | Create requires Enterprise |
| Segments | List, Get, Delete, Get Results | All with API access |
| Automations | List, Get | All with API access |
| Automation Journeys | Create, Get | All with API access |
| Custom Fields | List, Get, Delete | All with API access |
| Webhooks | List, Get, Create, Delete | Scale or above |
| Referral Program | Get | All with API access |
| Subscription Tags | List, Create, Delete | All with API access |
| Bulk Subscriptions | Bulk Create, Bulk Update | All with API access |
- Email sending/scheduling (beehiiv handles this through the dashboard)
- Media/image uploads
- Template management
MIT