How do I use Beehiiv Analytics MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Beehiiv Analytics MCP Server show me the top performing posts from last month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

This server provides read-only access to Beehiiv publication analytics and content data through the Model Context Protocol.

Publications - List all accessible publications and get detailed information about specific publications by ID

Posts - Retrieve posts for a publication with customizable limits (default: 10), access detailed post information by post ID, and view post statistics

Subscribers - List subscribers for a publication with customizable limits (default: 10) and get detailed information about specific subscribers by ID

Segments - List all audience segments for a publication and access detailed segment information by segment ID

All operations require appropriate publication IDs and some require additional identifiers. The server integrates with MCP-compatible clients like Claude Desktop and Cursor IDE.

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

git clone https://github.com/ousepachn/beehiivanalyticsMCP.git cd beehiivanalyticsMCP

Or download and extract the ZIP file from GitHub.

2. Create a Virtual Environment (Recommended)

python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Up Your API Key

Create a .env file in the project root:

cp .env.example .env

Then edit .env and add your Beehiiv API key:

BEEHIIV_API_KEY=your_api_key_here

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

Configuration

For Claude Desktop

Locate your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following configuration (adjust paths as needed):

{ "mcpServers": { "beehiiv-analytics": { "command": "/absolute/path/to/venv/bin/python3", "args": ["/absolute/path/to/beehiiv_mcp_server.py"], "env": { "BEEHIIV_API_KEY": "your_api_key_here" } } } }

Example for macOS:

{ "mcpServers": { "beehiiv-analytics": { "command": "/Users/yourusername/beehiivMCP/venv/bin/python3", "args": ["/Users/yourusername/beehiivMCP/beehiiv_mcp_server.py"], "env": { "BEEHIIV_API_KEY": "your_api_key_here" } } } }

Restart Claude Desktop

For Cursor IDE

Open Cursor settings
Navigate to MCP settings
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:

Copy the example file:

cp mcp_config.json.example mcp_config.json

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:

python test_beehiiv_api.py

Test the MCP Server

Run the example usage script:

python example_usage.py

Run All Tests

python test_all.py

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:

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:

Check the Troubleshooting section
Review the Beehiiv API Documentation
Open an issue on GitHub

Acknowledgments

Built for the Model Context Protocol
Uses the Beehiiv API

Beehiiv Analytics MCP Server