beehiiv_get_posts
Get posts from Beehiiv newsletter with comprehensive filtering options.
LABSCO SUMMARY
Newsletter admin without opening the dashboard.
The work it takes off you is the clicking: add a subscriber with the custom fields and campaign tags already attached, or pull the last ten posts with their titles and publish dates, in the same conversation where you were writing about them.
What it is
A connector between an AI client and the beehiiv API, covering the three things a newsletter operator touches daily: who is subscribed, what has been published, and which publication you are working in.
What you get
- Subscriptions — create one with custom fields and UTM values, or look a subscriber up by email or ID (
beehiiv_create_subscription) - Posts — fetch your published newsletters, pull a single post in full, filter by tag, date or audience type
- Publications — list your newsletters, read one publication's stats and settings, and work across several in one session
Requirements
A beehiiv account with API access. BEEHIIV_API holds the key, which starts with bh-, and BEEHIIV_PUBLICATION_ID pins a publication, which starts with pub_ — leave that one unset to work across newsletters and name the publication in each request instead. The prebuilt binary from the Releases page needs nothing else installed; building from source needs Java 21+ and the bundled ./mvnw. Set LOGGING_LEVEL_ROOT=DEBUG when a call fails and you need to see why.
Setup effort
One command plus credentials — curl -fsSL https://raw.githubusercontent.com/danvega/beehiiv-mcp-server/main/scripts/install.sh | bash, then supply credentials
USE CASES
01
Adding a subscriber you just met
Create the subscription with their name, role and company as custom fields in one sentence, instead of opening the dashboard and filling a form.
02
Attributing a signup to a campaign
Attach UTM source, medium and campaign at creation time so the subscriber arrives already tagged to the channel that brought them.
03
Reviewing what you have published
Pull your recent posts with titles and publish dates, filtered by tag or audience type, to see what the last stretch actually looked like.
04
Running more than one newsletter
Leave BEEHIIV_PUBLICATION_ID unset and name the publication per request, so a single connection covers every newsletter you own.
05
Checking whether someone is already on the list
Look a subscriber up by email or ID before adding them, so a duplicate signup does not become a duplicate record.
17 tools
Listed in project code.
beehiiv_get_post
Get a single post from the Beehiiv Newsletter API by post ID.
beehiiv_get_posts_by_status
Get posts filtered by status.
beehiiv_get_posts_by_platform
Get posts filtered by platform.
beehiiv_get_posts_by_tags
Get posts filtered by content tags.
beehiiv_get_publications
Get a list of all publications with filtering options.
beehiiv_get_publication
Get detailed information about a specific publication by ID.
beehiiv_get_current_publication
Get information about the currently configured publication
beehiiv_search_publications
Search publications by name using case-insensitive partial matching.
beehiiv_list_accessible_publications
List all publications accessible with the current API key
beehiiv_create_subscription
Create a new subscription/subscriber for a publication.
beehiiv_get_subscription_by_email
Retrieve a subscription by email address.
beehiiv_get_subscription_by_id
Retrieve a subscription by ID.
beehiiv_list_custom_fields
List all custom fields for a publication.
beehiiv_get_custom_field
Get details of a specific custom field.
beehiiv_get_custom_field_by_name
Find a custom field by name.
beehiiv_validate_custom_field_value
Validate a value against a custom field's type and constraints.
BEFORE YOU INSTALL
What to know first
Tools you get
17 tools registered in the project's code.
Requires
- BEEHIIV_API in your environment
- Java 21+ only for the Java build; the native binary needs nothing else installed
Optional
BEEHIIV_PUBLICATION_ID in your environment
INSTALLATION
Connect your client
Server setup
Go to Beehiiv API Settings and copy your API Key (starts with bh-) and your Publication ID (starts with pub_)
Download the binary: curl -fsSL https://raw.githubusercontent.com/danvega/beehiiv-mcp-server/main/scripts/install.sh | bash (or download the release asset for your OS manually)
TERMINAL
chmod +x beehiiv-mcp-server-*Add the mcpServers block to claude_desktop_config.json with the full path to that binary and your API key; set the Publication ID too only if you want to pin one newsletter
Restart Claude Desktop
MCP Clients
Claude Desktop — binary
CLAUDE DESKTOP — BINARY · JSON
{
"mcpServers": {
"beehiiv": {
"command": "<YOUR_PATH_TO_BEEHIIV_MCP_SERVER_LINUX>",
"env": {
"BEEHIIV_API": "<YOUR_BEEHIIV_API>",
"BEEHIIV_PUBLICATION_ID": "<YOUR_BEEHIIV_PUBLICATION_ID>"
}
}
}
}Claude Desktop — Java
CLAUDE DESKTOP — JAVA · TERMINAL
git clone https://github.com/danvega/beehiiv-mcp-server.git
cd beehiiv-mcp-server
./mvnw clean package -DskipTestsCLAUDE DESKTOP — JAVA · JSON
{
"mcpServers": {
"beehiiv": {
"command": "java",
"args": [
"-jar",
"<YOUR_PATH_TO_TARGET>/beehiiv-mcp-server-0.0.3-SNAPSHOT.jar"
],
"env": {
"BEEHIIV_API": "<YOUR_BEEHIIV_API>",
"BEEHIIV_PUBLICATION_ID": "<YOUR_BEEHIIV_PUBLICATION_ID>"
}
}
}
}This route needs Java 21 or newer. <YOUR_PATH_TO_TARGET> is the target/ folder in your clone; check the jar name there, since its version may differ from 0.0.3-SNAPSHOT.
