使用说明

Beehiiv MCP服务器

用于Beehiiv分析的模型上下文协议（MCP）服务器，提供对出版物、帖子和分段数据的读取权限，以及用于取消订阅的订阅者的受保护工具。

特性

出版物

列出所有出版物
获取详细的出版物信息

帖子

列出带有过滤选项（状态、受众、平台等）的帖子
通过可选的内容扩展获取详细的帖子信息
获取出版物中所有帖子的汇总统计信息

片段

列出出版物的所有部分
获取详细的细分市场信息

订阅者

通过电子邮件取消订阅一个或多个订阅者（默认情况下为模拟运行，可逆）

先决条件

Python 3.8或更高版本
A Beehiiv API密钥(在这里买一个)
MCP兼容客户端（例如，Claude Desktop、Cursor）

安装

1.克隆或下载此存储库

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

或者从GitHub下载并解压缩ZIP文件。

2.创建虚拟环境（推荐）

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

3.安装依赖项

pip install -r requirements.txt

4.设置API密钥

创造一个 .env 项目根目录中的文件：

cp .env.example .env

然后编辑 .env 并添加您的Beehiiv API密钥：

BEEHIIV_API_KEY=your_api_key_here

重要提示： 永远不要承诺你的 .env 文件到版本控制。它已经包含在 .gitignore.

配置

适用于克劳德桌面

找到您的Claude Desktop配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.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"
      }
    }
  }
}

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"
      }
    }
  }
}

重新启动克劳德桌面

用于游标IDE

打开光标设置
导航到MCP设置
添加类似于上面Claude Desktop的服务器配置

替代方案：使用mcp_gonfig.json

您还可以使用附带的 mcp_config.json.example 文件：

复制示例文件：

cp mcp_config.json.example mcp_config.json

编辑 mcp_config.json 并更新路径和API密钥

注：这个 mcp_config.json 文件在默认情况下被gitignored以保护您的API密钥。

测试

测试API连接

运行测试脚本以验证API密钥是否有效：

python test_beehiiv_api.py

测试MCP服务器

运行示例用法脚本：

python example_usage.py

运行所有测试

python test_all.py

可用工具

服务器提供以下MCP工具：

list_publications -列出使用API密钥可访问的所有出版物
get_publication_details -获取特定出版物的详细信息
list_posts -列出带有各种过滤器（状态、受众、平台、日期排序）的帖子
get_post_details -通过可选的内容扩展获取详细的帖子信息
get_posts_summary_stats -获取出版物中所有帖子的汇总统计信息
list_segments -列出出版物的所有部分
get_segment_details -获取特定细分市场的详细信息
unsubscribe_subscribers -通过电子邮件取消订阅（标记为非活动）一个或多个订阅者。默认为模拟运行，报告会发生什么变化；过 apply: true 真正做出改变。已经处于非活动状态或未找到的电子邮件将被跳过，因此可以安全地重新运行。

使用示例

与Claude Desktop一起使用

配置后，您可以询问Claude：

“列出我的所有出版物”
“显示出版物X的10个最新帖子”
“我最新帖子的统计数据是什么？”
“列出Y出版物的所有部分”
“告诉我如果我取消订阅会发生什么jane@example.com和john@example.com来自出版物X“（模拟版）
“取消订阅jane@example.com从出版物X“（通行证 apply: true 实际做出改变）

程序化使用

看 example_usage.py 用于直接使用API客户端的完整示例。

故障排除

API关键问题

确保在环境变量或配置文件中正确设置了API密钥
验证您的API密钥在 Beehiiv开发者门户
检查您的API密钥是否具有必要的权限

路径问题

在MCP配置中使用绝对路径
确保Python路径指向虚拟环境的Python
验证服务器脚本路径是否正确

连接问题

检查您的互联网连接
验证Beehiiv API是否可访问
检查防火墙设置（如适用）

API文档

有关API的详细信息，请参阅API官方文件：

贡献

欢迎投稿！请随时提交拉取请求。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

如果您遇到任何问题或有疑问：

检查故障排除部分
查看 API文件
在GitHub上打开一个问题

致谢

为模型上下文协议
使用 API比希夫