beehiiv-mcp

Beehiiv MCP

A Model Context Protocol (MCP) server for integrating with the Beehiiv newsletter platform. This MCP provides tools to interact with the Beehiiv API, allowing you to retrieve subscriber information and manage your newsletter operations programmatically.

🚀 Features

• Get Subscribers: Retrieve subscriber data with advanced filtering and pagination
• TypeScript Support: Full TypeScript implementation with proper error handling
• Environment Configuration: Secure API key and publication ID management
• Comprehensive Filtering: Support for status, tier, email, and custom field filtering
• Pagination Support: Cursor-based pagination for efficient data retrieval

🛠️ Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• A Beehiiv account with API access
• Your Beehiiv API key and Publication ID

Installation

• Clone this repository

  git clone https://github.com/beehiiv/beehiiv-mcp.git
  cd beehiiv-mcp
  

• Install dependencies

  npm install
  

• Configure environment variables

  cp .env .env.local
  

  Edit .env.local with your Beehiiv credentials:

  BEEHIIV_API_KEY=your_beehiiv_api_key_here
  BEEHIIV_PUBLICATION_ID=your_publication_id_here
  

• Get your Beehiiv credentials

  • API Key: Go to Beehiiv Integrations to generate your API key
  • Publication ID: Find this in your Beehiiv dashboard URL or API responses

• Start the MCP server

  npm run dev
  

Testing Your MCP Server

Using MCP Inspector

BEEHIIV_API_KEY=your_api_key BEEHIIV_PUBLICATION_ID=your_pub_id npx @modelcontextprotocol/inspector ./src/server.ts

Integrating with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "beehiiv": {
      "command": "node",
      "args": ["/path/to/beehiiv-mcp/src/server.ts"],
      "env": {
        "BEEHIIV_API_KEY": "your_beehiiv_api_key_here",
        "BEEHIIV_PUBLICATION_ID": "your_publication_id_here"
      }
    }
  }
}

🔧 Available Tools

get-subscribers

Retrieve subscribers from your Beehiiv publication with comprehensive filtering and pagination options.

Parameters:

• limit (optional): Number of results to return (1-100, default 10)
• cursor (optional): Pagination cursor for retrieving next page
• status (optional): Filter by subscription status
• tier (optional): Filter by subscription tier
• email (optional): Exact email match filter
• expand (optional): Array of fields to expand (premium tiers, referrals, stats, custom fields)
• order_by (optional): Sort field (defaults to 'created')
• direction (optional): Sort direction ('asc' or 'desc')

Example Usage:

// Get first 20 subscribers
await getSubscribers({ limit: 20 });

// Get active subscribers only
await getSubscribers({ status: "active", limit: 50 });

// Get subscribers with expanded data
await getSubscribers({
  expand: ["stats", "custom_fields"],
  limit: 10
});

// Paginate through results
await getSubscribers({
  cursor: "next_page_cursor_here",
  limit: 25
});

📁 Project Structure

beehiiv-mcp/
├── src/
│   └── server.ts          # Main MCP server with Beehiiv integration
├── .env                   # Environment variables template
├── .env.local            # Your actual environment variables (create this)
├── .gitignore            # Git ignore rules
├── LICENSE               # MIT license
├── README.md             # This documentation
├── manifest.json         # MCP manifest configuration
├── package.json          # Node.js package configuration
├── server.json           # MCP server configuration
└── tsconfig.json         # TypeScript configuration

🔒 Environment Variables

Configure these required environment variables in .env.local:

# Required: Your Beehiiv API key
# Get this from: https://app.beehiiv.com/settings/integrations
BEEHIIV_API_KEY=your_beehiiv_api_key_here

# Required: Your Beehiiv publication ID
# You can find this in your Beehiiv dashboard URL or API responses
BEEHIIV_PUBLICATION_ID=your_publication_id_here

📝 Available Scripts

• npm start - Start the MCP server
• npm run dev - Start with hot reload for development
• npm run build - Build the TypeScript project

🧪 Testing

Manual Testing with MCP Inspector

BEEHIIV_API_KEY=your_api_key BEEHIIV_PUBLICATION_ID=your_pub_id npx @modelcontextprotocol/inspector ./src/server.ts

Integration Testing

Test your MCP by integrating it with Claude Desktop using the configuration mentioned in the Quick Start section.

🔍 API Reference

This MCP integrates with the Beehiiv API v2. Specifically:

• Endpoint: GET /v2/publications/{publicationId}/subscriptions
• Authentication: Bearer token (your API key)
• Documentation: Beehiiv Subscriptions API

📚 Documentation Links

• Beehiiv API Documentation
• MCP Specification
• MCP SDK Documentation
• Claude Desktop Integration

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

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

🆘 Support

If you encounter any issues:

• Check that your BEEHIIV_API_KEY and BEEHIIV_PUBLICATION_ID are correctly set
• Verify your API key has the necessary permissions in Beehiiv
• Review the Beehiiv API documentation
• Open an issue in this repository

🎯 Future Enhancements

Potential additions to this MCP:

• Create/update subscriber tools
• Newsletter management tools
• Analytics and reporting tools
• Webhook management
• Campaign creation and sending

Happy newsletter managing! 📧