Beehiiv Analytics

Provides read-only Beehiiv publications, posts, and segments data through an MCP server for easy client integration.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You run an MCP server that exposes Beehiiv analytics data as read-only endpoints for publications, posts, and segments. It lets you connect via an MCP client to list and inspect data without managing API calls yourself, making it easy to build insights and workflows around Beehiiv content.

How to use

Connect to the Beehiiv MCP server from your MCP client to query publications, posts, and segments. You can list all publications you have access to, view detailed information about a publication, list and filter posts, see aggregate post statistics, and explore segments for a publication. Use your client’s standard MCP commands or UI actions to access these functions.

How to install

Prerequisites you need before starting are Python 3.8 or higher, a Beehiiv API key, and an MCP-compatible client such as Claude Desktop or Cursor.

Clone the project repository and install dependencies.

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

Create and activate a virtual environment, then install Python dependencies.

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Set up your API key in a configuration file.

cp .env.example .env

then edit so it contains your Beehiiv API key:

BEEHIIV_API_KEY=your_api_key_here

Run the MCP server directly after configuring the key. The server is started via a Python command in your environment.

# Example runtime (adjust paths to your setup)
/absolute/path/to/venv/bin/python3 /absolute/path/to/beehiiv_mcp_server.py

Configuration and startup tips

To integrate with Claude Desktop or Cursor IDE, you configure an MCP server entry that launches the same Python runtime and points at the server script, with your API key passed as an environment variable.

Values shown here are representative and should be adjusted to your actual installation paths.

Using mcp_config.json

You can also configure MCP servers using a dedicated config file. Copy the example, then customize the paths and your API key.

cp mcp_config.json.example mcp_config.json

Then edit the file to match your environment. The file is gitignored to protect your API key.


## Available 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 filters such as status, audience, platform, and date sort

### get\_post\_details

Get detailed post information with optional content expansion

### get\_posts\_summary\_stats

Get aggregate statistics for all posts within a publication

### list\_segments

List all segments for a publication

### get\_segment\_details

Get detailed information about a specific segment