beehiiv
MCP server from danvega/beehiiv-mcp-server
claude mcp add --transport stdio danvega-beehiiv-mcp-server java -jar /FULL/PATH/TO/target/beehiiv-mcp-server-0.0.3-SNAPSHOT.jar \ --env BEEHIIV_API="bh-your-api-key-here" \ --env BEEHIIV_PUBLICATION_ID="pub-your-publication-id-here"
How to use
Beehiiv MCP Server enables Claude Desktop and other AI assistants to manage your Beehiiv newsletter via natural language. It exposes a set of tools that map directly to Beehiiv API capabilities, including subscriber management, post/content retrieval, and publication management. You can ask Claude to add subscribers, fetch recent posts, or list your publications, and the MCP server translates those requests into Beehiiv API calls behind the scenes. The setup supports using a single publication or multiple publications by configuring the relevant API key and publication IDs in the environment and requests. The included tools are designed to be intuitive: you can create subscriptions with custom fields, retrieve posts with filtering, and get detailed publication information for analytics and targeting. To get started, pair Claude Desktop with the Beehiiv MCP server following the configuration example, then try simple prompts like adding a subscriber or listing recent posts.
How to install
Prerequisites:
- Java 21+ (recommended) and Maven (or the included Maven wrapper in the repo)
- Beehiiv account with API access and a publication to manage
- Claude Desktop (for testing and usage via MCP integration)
Installation steps:
-
Clone the repository and navigate into it git clone <this-repo> cd beehiiv-mcp-server
-
Build the project (produces a runnable JAR) ./mvnw clean package -DskipTests
-
Locate the built JAR in target, for example: target/beehiiv-mcp-server-0.0.3-SNAPSHOT.jar
-
Configure Claude Desktop with the Java-based server Create or edit your Claude configuration to point to the jar, for example: { "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" } } } }
-
(Optional) Run in HTTP mode for testing: java -jar target/beehiiv-mcp-server-0.0.2-SNAPSHOT.jar Then configure Claude Desktop with the HTTP URL (e.g., http://localhost:8080/mcp) as described in the README.
Additional notes
Tips and common notes:
- Ensure your Beehiiv API key starts with bh- and that the key is copied without extra spaces.
- Publication IDs should start with pub_. If you manage multiple publications, omit the BEEHIIV_PUBLICATION_ID in the global env and specify it per request where supported.
- If you encounter issues in Claude Desktop, verify that the JAR path is absolute, environment variables are set, and that the MCP server process has started without errors.
- You can swap to the native binary or a Java build as described in the README; both approaches are supported by the same MCP protocol.
- For development or testing, enable debug logging by setting LOGGING_LEVEL_ROOT=DEBUG in the environment.
- The MCP tools exposed include: Add/Find subscribers, Get posts, Single post details, List publications, and publication details. You can filter posts by tags, date, or audience type as per the Beehiiv API capabilities.
