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
- macOS:
-
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.jsonand 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 keyget_publication_details- Get detailed information about a specific publicationlist_posts- List posts with various filters (status, audience, platform, date sorting)get_post_details- Get detailed post information with optional content expansionget_posts_summary_stats- Get aggregate statistics for all posts in a publicationlist_segments- List all segments for a publicationget_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