# Beehiiv MCP Server

A Model Context Protocol (MCP) server for Beehiiv analytics, providing read access to publications, posts, and segments data, plus a guarded tool for unsubscribing subscribers.

## 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

### Subscribers
- Unsubscribe one or more subscribers by email (dry-run by default, reversible)

## Prerequisites

- Python 3.8 or higher
- A Beehiiv API key ([Get one here](https://developers.beehiiv.com/welcome/getting-started))
- An MCP-compatible client (e.g., Claude Desktop, Cursor)

## Installation

### 1. Clone or Download this Repository

```bash
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)

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

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Set Up Your API Key

Create a `.env` file in the project root:

```bash
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

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):

```json
{
  "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:**
```json
{
  "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"
      }
    }
  }
}
```

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:
```bash
cp mcp_config.json.example mcp_config.json
```

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:

```bash
python test_beehiiv_api.py
```

### Test the MCP Server

Run the example usage script:

```bash
python example_usage.py
```

### Run All Tests

```bash
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
- **`unsubscribe_subscribers`** - Unsubscribe (mark inactive) one or more subscribers by email. Defaults to a dry run that reports what would change; pass `apply: true` to actually make the change. Already-inactive or not-found emails are skipped, so it's safe to re-run.

## 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"
- "Show me what would happen if I unsubscribed jane@example.com and john@example.com from publication X" (dry run)
- "Unsubscribe jane@example.com from publication X" (pass `apply: true` to actually make the change)

### 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](https://developers.beehiiv.com/welcome/getting-started)
- 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](https://developers.beehiiv.com/welcome/getting-started)
- [Publications API](https://developers.beehiiv.com/api-reference/publications/index)
- [Posts API](https://developers.beehiiv.com/api-reference/posts/index)
- [Segments API](https://developers.beehiiv.com/api-reference/segments/index)

## Contributing

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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions:

1. Check the [Troubleshooting](#troubleshooting) section
2. Review the [Beehiiv API Documentation](https://developers.beehiiv.com/)
3. Open an issue on GitHub

## Acknowledgments

- Built for the [Model Context Protocol](https://modelcontextprotocol.io/)
- Uses the [Beehiiv API](https://developers.beehiiv.com/)