Bison MCP

EmailBison MCP服务器

模型上下文协议（MCP）服务器的Python实现，该服务器将Claude连接到 电子邮件。 API该服务器公开了用于在EmailBison工作区内管理潜在客户、活动和直接发送的精心策划的工具。

特性

• 多账户支持：通过以下方式管理多个EmailBison帐户 config.json
• 使用API密钥进行安全连接（通过 config.json 或 EMAILBISON_API_KEY 环境变量）
• 列出并创建潜在客户
• 列出活动并起草新活动，可选择立即发送
• 从任何配置的EmailBison发件人帐户发送临时电子邮件
• Claude工具参数和结构化结果的JSON模式验证
• 丰富的MCP元数据：资源展示快速参考文档，提示说明常见的自动化流程

项目布局

• emailbison_mcp/client.py –EmailBison的轻量级异步HTTP客户端
• emailbison_mcp/server.py –MCP服务器定义和工具处理程序
• pyproject.toml –项目元数据和运行时依赖关系

先决条件

• Python 3.10+
• EmailBison API密钥，可访问您的工作空间
• pipx 或 pip 用于安装依赖项

安装

pip install -e .

或者，在虚拟环境中：

python -m venv .venv
.venv\\Scripts\\activate  # PowerShell
pip install -e .

配置

多账户模式（推荐）

创建 config.json 文件在 emailbison_mcp/ 目录具有以下结构：

{
  "clients": {
    "Account1": {
      "mcp_key": "your-api-key-here",
      "mcp_url": "https://send.longrun.agency/api"
    },
    "Account2": {
      "mcp_key": "another-api-key-here",
      "mcp_url": ""
    }
  },
  "default_client": "Account1"
}

重要：从不承诺 config.json 版本控制。添加到 .gitignore.

所有工具都接受可选 client_name 参数指定要使用的帐户。如果没有提供 default_client 使用config.json。

看 document:emailbison/multi-account-config 查看详细的配置文档。

单账户模式（向后兼容）

如果 config.json 如果找不到，服务器将回退到环境变量。复制 .env.example 到 .env （或配置您的shell）：

EMAILBISON_API_KEY=51|LYXIxPC5LeEsdEwK3Yn37hOfeQkcLsOBbKEsfsID07a9c1cc
EMAILBISON_BASE_URL=https://send.longrun.agency/api
EMAILBISON_TIMEOUT_SECONDS=30

EMAILBISON_BASE_URL 和 EMAILBISON_TIMEOUT_SECONDS 是可选的覆盖。默认基本URL为 https://send.longrun.agency/api.

运行服务器

python -m emailbison_mcp.server

入口点通过stdio与MCP通信。要连接Claude Desktop或其他兼容MCP的客户端：

1. 注册可执行文件(python -m emailbison_mcp.server)作为一种定制工具。
2. 确保环境变量对流程可用。
3. 启动客户端——Claude将自动发现EmailBison工具。

可用工具

• list_leads –分页的潜在客户查找。
• get_lead –通过ID或电子邮件地址检索特定潜在客户的详细信息。返回全面的信息，包括联系人详细信息、状态、自定义变量、活动数据和统计数据。
• create_lead –创建单个潜在客户（联系人）记录。需要电子邮件、first_name和last_name。支持可选的公司、标题、注释、自定义变量（名称/值对象数组）和标签。
• update_lead –通过ID或电子邮件地址更新特定潜在客户的详细信息。所有字段都是可选的。只有请求中传递的字段才会被更新；未传递的字段和自定义变量将保持不变。
• unsubscribe_lead –取消订阅预定电子邮件中的潜在客户。停止向潜在客户发送所有未来计划的电子邮件。返回状态设置为“未订阅”的更新潜在客户。
• bulk_create_leads_csv –使用CSV文件在单个请求中创建多个潜在客户。要求CSV内容为字符串、列映射配置（电子邮件、first_name、last_name为必填项；公司、标题、custom_variable为可选项）和列表名称。支持现有的潜在客户行为选项（放置、修补、跳过）。
• list_campaigns –使用可选的搜索、状态和标签ID过滤器查看活动。
• create_campaign –使用名称、可选类型和高级设置有效负载创建活动。
• send_email –通过发件人帐户发送直接电子邮件。
• get_account_details –检查经过身份验证的用户的个人资料和工作空间限制。
• list_workspaces –检索已验证用户的所有工作区。返回工作区详细信息，包括ID、姓名、personal_team标志、主标志、电子邮件验证信用、发件人电子邮件限制、预热限制、访问标志和时间戳。
• create_workspace –为经过身份验证的用户创建一个新的工作区。需要工作区名称。返回创建的工作区对象，其中包含所有工作区详细信息，包括ID、名称、标志、限制、信用和时间戳。
• switch_workspace –为经过身份验证的用户切换到其他工作区。更改活动工作区上下文。需要目标工作区的team_id（工作区id）。使用list_workspaces获取可用的工作区ID。返回切换到的工作区的名称。
• update_workspace –更新已验证用户的工作区信息，特别是工作区名称。需要更新工作区的team_id（工作区id）和新名称。使用list_workspaces获取可用的工作区ID。返回更新的工作区名称。
• get_workspace_details –检索经过身份验证的用户的特定工作区的详细信息。返回全面的工作区信息，包括ID、名称、标志、电子邮件验证信用、发件人电子邮件限制、预热限制、访问标志和时间戳。需要检索工作区的team_id（工作区id）。使用list_workspaces获取可用的工作区ID。
• invite_team_member –邀请新成员加入已验证用户的团队（工作区）。需要新团队成员的电子邮件地址和角色。返回创建的团队成员邀请对象，包括ID、UUID、workspace_ID、电子邮件、角色和时间戳。
• get_workspace_stats –检索两个给定日期之间经过身份验证的用户工作区的总体统计数据。返回全面的指标，包括发送的电子邮件、联系的潜在客户总数、打开次数（计数和百分比）、每个联系人的唯一打开次数（计数值和百分比），每个联系人的独特回复次数（计值和百分比）。需要start_date和end_date参数。
• get_workspace_line_area_chart_stats –按日期检索经过身份验证的用户工作区在给定时间段内的完整标准化统计数据。返回事件的时间序列数据：已回复、总打开次数、唯一打开次数、已发送、已跳出、未订阅和感兴趣。每个事件都包含一个标签、颜色和日期数组，其中包含用于绘制图表的日期值对。需要start_date和end_date参数。
• list_tags –检索工作区标签；在筛选潜在客户时使用返回的ID。
• list_custom_variables –检索工作区的所有自定义变量。返回带有ID、名称和时间戳的变量。自定义变量可用于电子邮件模板和潜在客户数据。
• create_custom_variable –为工作区创建一个新的自定义变量。指定变量名称。返回创建的变量及其ID、名称和时间戳。
• get_tag –通过ID检索特定标签。返回标签详细信息，包括名称、默认状态和时间戳。
• create_tag –在工作区中创建一个新标签。指定标记名称，并可选择将其标记为默认值。
• delete_tag –按ID删除标签。返回一条成功消息，确认标签已被删除。
• attach_tags_to_campaigns –在一次操作中为多个活动附加多个标签。需要活动ID和标签ID的数组。
• remove_tags_from_campaigns –在一次操作中从多个活动中分离多个标签。需要活动ID和标签ID的数组。
• attach_tags_to_leads –在一次操作中将多个标签附加到多个引线上。需要潜在客户ID和标签ID数组。
• remove_tags_from_leads –在一次操作中从多个引线上拆下多个标签。需要潜在客户ID和标签ID数组。
• attach_tags_to_sender_emails –在一次操作中为多个电子邮件帐户（发件人电子邮件）附加多个标签。需要发件人电子邮件ID和标签ID的数组。
• remove_tags_from_sender_emails –在一次操作中从多个电子邮件帐户（发件人电子邮件）中分离多个标签。需要发件人电子邮件ID和标签ID的数组。
• duplicate_campaign –按ID克隆现有活动。
• pause_campaign –使用活动ID暂停活动。
• resume_campaign –使用其ID恢复暂停的活动。
• archive_campaign –使用活动ID存档活动。
• update_campaign_settings –修补活动限制、取消订阅文本和其他标志。
• create_campaign_schedule –定义活动发送日期、时间和时区。
• get_campaign_schedule –检索活动的当前计划配置。
• update_campaign_schedule –替换现有的活动计划。
• list_schedule_templates –查看工作区的所有已保存计划模板。
• list_schedule_timezones –查看活动日程的所有可用时区（使用ID字段）。
• get_sending_schedules –查看特定日期（今天、明天或day_after_tomorrow）的活动发送时间表。
• get_campaign_sending_schedule –查看特定活动在给定日期的发送时间表。
• create_campaign_schedule_from_template –使用保存的计划模板创建活动计划。
• get_campaign_sequence_steps –查看活动的顺序步骤，包括电子邮件主题、正文、等待时间和其他详细信息。
• create_campaign_sequence_steps –使用电子邮件主题、正文、等待时间和可选变体设置从头开始创建活动序列步骤。
• update_campaign_sequence_steps –更新现有的活动序列步骤。包括现有步骤的步骤ID以更新它们。
• delete_sequence_step –从序列中删除特定的序列步骤。
• send_sequence_step_test_email –从序列步骤发送测试电子邮件。需要在活动中至少有一个领先优势。
• get_campaign_details –检索特定活动的详细信息。返回全面的信息，包括ID、UUID、名称、类型、状态、完成百分比、电子邮件统计、潜在客户计数、设置、时间戳和标签。
• list_replies –检索所有活动中已验证用户的所有回复。支持按搜索、状态、文件夹、阅读状态、活动、发件人电子邮件、潜在客户、标签等进行过滤。返回分页结果。
• get_lead_replies –通过ID或电子邮件地址检索特定潜在客户的所有回复。支持按搜索、状态、文件夹、阅读状态、活动、发件人电子邮件和标签进行过滤。
• get_lead_scheduled_emails –通过ID或电子邮件地址检索特定潜在客户的所有预定电子邮件。返回预定的电子邮件详细信息，包括状态、预定日期、参与度指标以及完整的潜在客户和发件人电子邮件信息。
• get_lead_sent_emails –通过ID或电子邮件地址检索特定潜在客户的所有已发送活动电子邮件。返回已发送电子邮件的详细信息，包括状态、计划日期、发送日期和参与度指标（打开、点击、回复、感兴趣）。
• get_reply –按ID检索特定回复。返回包括回复详细信息、邮件内容、附件和相关元数据在内的全面信息。
• compose_new_email –在新的电子邮件线程中发送一次性电子邮件（不是对现有对话的回复）。支持HTML/文本内容、多个收件人（收件人、抄送、密送）、附件和专用IP选项。
• create_reply –回复现有的电子邮件帖子。支持HTML/文本内容、多个收件人（收件人、抄送、密件抄送）、附件、注入以前电子邮件正文的选项和专用IP选项。
• get_campaign_replies –检索与特定活动相关的所有回复。支持按搜索、状态、文件夹、阅读状态、发件人电子邮件、潜在客户、标签等进行过滤。返回分页结果。
• get_campaign_leads –检索与活动相关的所有潜在客户。支持按搜索词和复杂过滤器过滤状态、发送的电子邮件、打开、回复、验证状态、标签和日期。
• remove_campaign_leads –通过提供潜在客户ID从活动中删除一个或多个潜在客户。
• import_campaign_leads_from_list –将现有潜在客户列表中的潜在客户导入活动。允许通过引用潜在客户列表ID一次添加多个潜在客户。
• import_campaign_leads_by_ids –通过ID将潜在客户导入活动。对于活跃的活动，潜在客户会在本地缓存，并每5分钟同步一次。对于回复跟进活动，从上次发送的回复开始。
• stop_future_emails_for_leads –停止为活动中选定的潜在客户发送未来的电子邮件。防止活动向指定的潜在客户发送额外的电子邮件。
• get_campaign_scheduled_emails –检索与活动相关的所有预定电子邮件。返回详细信息，包括主题、正文、状态、计划日期、潜在客户信息和发件人电子邮件详细信息。支持按计划日期、本地计划日期和状态进行筛选。
• list_sender_emails –检索与经过身份验证的工作区关联的所有电子邮件帐户（发件人电子邮件）。返回详细信息，包括姓名、电子邮件地址、电子邮件签名、IMAP/SMTP设置、每日限制、类型、状态、统计信息和标签。支持按搜索词、标记ID、排除的标记ID和没有标记的帐户进行筛选。
• list_sender_emails_with_warmup_stats –使用预热统计信息检索所有电子邮件帐户（发件人电子邮件）。返回电子邮件帐户详细信息和预热指标（发送的电子邮件、收到的回复、从垃圾邮件中保存的电子邮件、预热分数、跳出次数）。需要start_date和end_date参数。支持按搜索词、标记ID、排除的标记ID、没有标记的帐户、预热状态（启用/禁用）和MX记录状态（记录丢失/记录有效）进行筛选。
• enable_warmup_for_sender_emails –为选定的电子邮件帐户启用预热。此操作启用了所有指定发件人电子邮件ID的预热过程，通过逐渐增加发送量来提高电子邮件的送达率。返回成功消息。注意：如果电子邮件帐户列表较长，此操作可能需要几分钟时间。
• disable_warmup_for_sender_emails –禁用所选电子邮件帐户的预热。此操作禁用所有指定发件人电子邮件ID的预热过程。预热电子邮件将在24小时内缓慢下降。返回成功消息。注意：如果电子邮件帐户列表较长，此操作可能需要几分钟时间。
• update_daily_warmup_limits –更新选定电子邮件帐户的每日预热限制。设置为指定发件人电子邮件ID发送的预热电子邮件的每日限制。您还可以选择设置每日回复限制（可以设置为“自动”字符串）。警告：只有当收件箱经销商明确告知时，才应使用daily_reply_limit参数。返回成功消息。
• get_sender_email_with_warmup_details –检索单个电子邮件帐户（发件人电子邮件）及其预热详细信息。返回指定日期范围内的电子邮件帐户详细信息（ID、电子邮件、姓名、域名、标签）和预热指标（发送的电子邮件、收到的回复、从垃圾邮件中保存的电子邮件、预热分数、跳出次数）。需要sender.email_id（id或电子邮件地址）、start_date和end_date参数。
• get_campaign_sender_emails –检索与活动相关的所有电子邮件帐户（发件人电子邮件）。返回详细信息，包括姓名、电子邮件地址、IMAP/SMTP设置、每日限制、状态、统计信息和标签。
• get_campaign_stats –检索指定日期范围内的活动统计信息（摘要）。返回总体指标（发送的电子邮件、打开的邮件、回复、反弹等）和每个序列的步骤统计数据。
• get_campaign_line_area_chart_stats –按日期检索给定时间段的完整标准化统计数据。返回事件的时间序列数据：已回复、总打开次数、唯一打开次数、已发送、已跳出、未订阅和感兴趣。每个事件都包含用于绘制图表的日期值对。
• attach_sender_emails_to_campaign –通过提供发件人的电子邮件ID将发件人的电子邮件附加到活动中。配置将用于发送活动电子邮件的电子邮件帐户。
• remove_sender_emails_from_campaign –通过提供发件人电子邮件ID，从草稿或暂停的活动中删除发件人电子邮件。注意：此操作只能对处于草稿或暂停状态的活动执行。

每个工具都为Claude返回一个结构化的JSON有效负载和一个格式化的文本摘要。

重要提示：分页 -许多端点返回分页结果（默认情况下每页15个条目）。在获取数据时始终使用分页。检查 links.next 在响应中输入字段以获取下一页，或使用 page 用于获取特定页面的参数。有关详细信息，请参阅分页资源。

资源

• document:emailbison/api-reference –关键REST端点和过滤器提示。
• document:emailbison/mcp-variables –配置选项（多帐户和单帐户模式）。
• document:emailbison/multi-account-config –设置多个帐户的详细指南。
• document:emailbison/pagination –处理已分页API响应的指南。
• document:emailbison/account-details –使用说明 GET /users 帐户元数据端点。
• document:emailbison/tags –检索标签ID并在过滤器中使用它们的指南。

Claude可以通过MCP资源浏览器阅读这些文档以获得快速提醒。

提示模板

• list-interested-leads –显示响应线索的示例请求。
• review-active-campaigns –使用参与度指标审核正在进行的外联活动。
• summarise-account-limits –提取帐户元数据并突出显示与配额相关的字段。
• filter-leads-by-tag –在筛选潜在客户之前获取标签ID的演练。

在与Claude协调工作流程时，按原样使用或调整它们。

发展

pip install -r requirements.txt  # if you prefer requirements files
ruff check
pytest

该项目目前使用 httpx, pydantic, anyio，以及 mcp.

参考文献

• EmailBison API文档：https://docs.emailbison.com/get-started
• 模型上下文协议规范：https://docs.anthropic.com/en/docs/model-context-protocol

许可证

麻省理工学院——见 LICENSE 如果添加。