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

1. Install uv if you haven’t already:

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

2. 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

3. 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:

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

(video coming soon)

Troubleshooting

Server Not Showing Up in Claude

1. Check your claude_desktop_config.json file syntax
2. Ensure all paths are absolute, not relative
3. 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)