Beehiiv MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Beehiiv API v2. This server enables Large Language Models (LLMs) to interact with Beehiiv publications and posts through standardized tools.

Prerequisites

Python 3.10 or higher
uv package manager
A Beehiiv account with API access
Claude Desktop (or another MCP-compatible client)

Installation

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

If rebuilding from scratch, create and set up your project:

# Create a new directory and navigate into it
mkdir beehiiv-mcp-server
cd beehiiv-mcp-server

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx python-dotenv

Create a .env file in the project root:

BEEHIIV_API_KEY=your_api_key_here
BEEHIIV_PUBLICATION_ID=your_publication_id_here

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "beehiiv-mcp-server": {
      "command": "<ABSOLUTE_UV_PATH>",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<ABSOLUTE_SERVER_PATH>"
      ]
    }
  }
}

Replace:

<ABSOLUTE_UV_PATH> with the path to your uv executable
<ABSOLUTE_SERVER_PATH> with the absolute path to your beehiiv_server.py file

Available Tools

This MCP server currently exposes the following tools (more will be added):

list_publications

Lists all publications accessible with your API key.

list_posts

Lists the 5 most recent confirmed posts for a given publication.

list_posts(publication_id: str)

get_post

Retrieves detailed information about a specific post.

get_post(publication_id: str, post_id: str)

How It Works

When you interact with this server through Claude Desktop:

The client sends your question to Claude
Claude analyzes the available Beehiiv tools and decides which one(s) to use
The client executes the chosen tool(s) through this MCP server
The results are sent back to Claude
Claude formulates a natural language response
The response is displayed to you

(video coming soon)

Troubleshooting

Server Not Showing Up in Claude

Check your claude_desktop_config.json file syntax
Ensure all paths are absolute, not relative
Restart Claude Desktop

Viewing Logs

Check Claude's logs for MCP-related issues:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Logs are stored in:

~/Library/Logs/Claude/mcp.log for general MCP connections
~/Library/Logs/Claude/mcp-server-beehiiv-mcp-server.log for server-specific logs

Security

Never commit your .env file to version control
Keep your Beehiiv API key secure
Consider implementing rate limiting for API calls

Contributing

hmu on X (https://x.com/reymerekar7)

Integrations