Beehiiv MCP Server

A Model Context Protocol (MCP) server for Beehiiv analytics, providing read-only access to publications, posts, and segments data.

Features

Publications

• List all publications

• Get detailed publication information

Posts

• List posts with filtering options (status, audience, platform, etc.)

• Get detailed post information with optional content expansion

• Get aggregate statistics for all posts in a publication

Segments

• List all segments for a publication

• Get detailed segment information

Prerequisites

• Python 3.8 or higher

• A Beehiiv API key (Get one here)

• An MCP-compatible client (e.g., Claude Desktop, Cursor)

Installation

1. Clone or Download this Repository

Or download and extract the ZIP file from GitHub.

2. Create a Virtual Environment (Recommended)

3. Install Dependencies

4. Set Up Your API Key

Create a .env file in the project root:

Then edit .env and add your Beehiiv API key:

Important: Never commit your .env file to version control. It's already included in .gitignore.

Configuration

For Claude Desktop

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following configuration (adjust paths as needed):

Example for macOS:

3. Restart Claude Desktop

For Cursor IDE

1. Open Cursor settings

2. Navigate to MCP settings

3. Add the server configuration similar to Claude Desktop above

Alternative: Using mcp_config.json

You can also use the included mcp_config.json.example file:

1. Copy the example file:

2. Edit mcp_config.json and update the paths and API key

Note: The mcp_config.json file is gitignored by default to protect your API key.

Testing

Test API Connectivity

Run the test script to verify your API key works:

Test the MCP Server

Run the example usage script:

Run All Tests

Available Tools

The server provides the following MCP tools:

• list_publications - List all publications accessible with your API key

• get_publication_details - Get detailed information about a specific publication

• list_posts - List posts with various filters (status, audience, platform, date sorting)

• get_post_details - Get detailed post information with optional content expansion

• get_posts_summary_stats - Get aggregate statistics for all posts in a publication

• list_segments - List all segments for a publication

• get_segment_details - Get detailed information about a specific segment

Usage Examples

Using with Claude Desktop

Once configured, you can ask Claude:

• "List all my publications"

• "Show me the 10 most recent posts from publication X"

• "What are the stats for my latest post?"

• "List all segments for publication Y"

Programmatic Usage

See example_usage.py for a complete example of using the API client directly.

Troubleshooting

API Key Issues

• Make sure your API key is set correctly in the environment variable or config file

• Verify your API key is valid at the Beehiiv Developer Portal

• Check that your API key has the necessary permissions

Path Issues

• Use absolute paths in your MCP configuration

• Ensure the Python path points to your virtual environment's Python

• Verify the server script path is correct

Connection Issues

• Check your internet connection

• Verify the Beehiiv API is accessible

• Check firewall settings if applicable

API Documentation

For detailed API information, refer to the official Beehiiv API documentation:

• Getting Started

• Publications API

• Posts API

• Segments API

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section

2. Review the Beehiiv API Documentation

3. Open an issue on GitHub

Acknowledgments

• Built for the Model Context Protocol

• Uses the Beehiiv API