内容
# Woodpecker MCP 服务器
Woodpecker MCP（Model Context Protocol）集成将冷邮件活动管理转变为对话式体验。
通过将您的 AI 助手连接到 Woodpecker 强大的自动化平台，您可以通过自然语言交互创建、管理和优化邮件活动。
从列出活动和创建基本外联序列等简单命令开始。然后逐渐探索高级功能，如 A/B 测试、复杂跟进序列和详细分析报告。
## 功能
- **活动管理**：创建、更新、运行、暂停和删除邮件活动
- **潜在客户操作**：添加潜在客户到您的账户和活动，更新和删除潜在客户数据，搜索潜在客户
- **邮件撰写**：创建带有 A/B 测试功能的分步邮件序列
- **分析和报告**：获取活动统计数据和性能指标
- **邮箱集成**：将邮件账户分配给活动
- **高级配置**：支持投递计划、时区设置和 GDPR 合规性
## 安装
### 先决条件
在设置集成之前，请确保您具备：
- **Woodpecker 账户**：具有启用 API & Integration 插件的账户
- **API 凭证**：Woodpecker API 密钥（在您的账户设置中找到）
- **Docker**：在您的系统上安装（用于运行 MCP 服务器） [https://docs.docker.com/desktop/](https://docs.docker.com/desktop/)
- **AI 代理**：Claude Desktop、Continue.dev 或其他兼容 MCP 的 AI 平台
### 获取 Woodpecker API 密钥
1. 登录到 Woodpecker 账户 ([https://login.woodpecker.co/](https://login.woodpecker.co/))
2. 进入右上角的市场 → 集成 → 'API 密钥'
3. 点击 `创建密钥`
### AI 代理配置
#### Claude Desktop
##### 步骤 1：定位配置文件
找到您的 Claude Desktop 配置文件：
**macOS：**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows：**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**Linux：**
```
~/.config/Claude/claude_desktop_config.json
```
##### 步骤 2：添加 MCP 服务器配置
编辑配置文件以包含 Woodpecker MCP 服务器：
```json
{
"mcpServers": {
"woodpecker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"WOODPECKER_API_KEY",
"woodpeckerco/woodpecker-mcp-server"
],
"env": {
"WOODPECKER_API_KEY": "<YOUR_API_KEY>"
}
}
}
}
```
##### 步骤 3：重启 Claude Desktop
1. 完全退出 Claude Desktop
2. 重新启动应用程序
3. 在界面中查找 Woodpecker 工具
### 其他 MCP 兼容代理
对于其他支持 MCP 的 AI 平台：
1. **确保 MCP 支持**：验证您的 AI 代理是否支持 Model Context Protocol
2. **身份验证**：通过环境变量提供 Woodpecker API 凭证 (`WOODPECKER_API_KEY`)
3. **协议**：使用 stdio 传输协议，支持您的代理
### 验证和测试
在您的 AI 代理中，尝试询问：
```
"你有哪些 Woodpecker 工具？"
"列出我的 Woodpecker 活动"
```
### 故障排除
#### MCP 服务器无法连接
**症状：** AI 代理无法访问 Woodpecker 工具
**解决方案：**
1. 在 MCP 服务器配置中尝试使用绝对 Docker 路径（例如 `/usr/local/bin/docker`）
2. 检查 Docker 容器是否正在运行：`docker ps`
3. 测试 API 密钥：直接向 Woodpecker 发出 API 调用
#### 无效 API 凭证
**症状：** “Unauthorized” 或 “Invalid API key” 错误
**解决方案：**
1. 在 Woodpecker 设置中重新生成 API 密钥
2. 使用新密钥更新环境变量
3. 重启 AI 代理应用程序
#### 工具不可用
**症状：** AI 代理看不到 Woodpecker 功能
**解决方案：**
1. 检查 AI 代理中的 MCP 服务器配置
2. 重启 AI 代理应用程序
3. 检查 AI 代理日志中的 MCP 连接错误
#### 活动创建失败
**症状：** 创建活动时出错
**解决方案：**
1. 确保在 Woodpecker 中至少有一个配置好的邮箱账户
2. 使用 `listMailboxes` 功能验证邮箱账户 ID
3. 检查活动参数是否符合要求的格式
4. 确保每日注册限制 > 0
## 使用示例
### 创建您的第一个活动
```
"使用以下详细信息创建一个新的邮件活动：
- 名称：产品演示外联
- 主题：我们新功能的快速演示
- 消息：嗨 {{FIRST_NAME}}，我很乐意向 {{COMPANY}} 展示我们的新功能。你是否有空进行 15 分钟的演示？
- 发送时间：周一至周五，9 点至 17 点
- 每日限制：25 个潜在客户
- 使用我的主邮箱账户"
```
### 批量添加潜在客户
```
"将以下潜在客户添加到活动 12345：
1. John Doe, john@example.com, Example Corp, 营销总监
2. Jane Smith, jane@example.com, Tech Solutions, 首席执行官
3. Bob Johnson, bob@example.com, Startup Inc, 首席技术官
对每个潜在客户使用此个性化内容：
- John：'我看到了您最近关于电子邮件营销的博客文章'
- Jane：'祝贺您最近获得资金'
- Bob：'您的产品发布看起来令人印象深刻'"
```
### 活动管理
```
"暂停活动 12345 并显示其性能统计数据"
"将活动 '产品演示外联' 更新为每天仅发送 15 个潜在客户"
"在活动 12345 中添加一个跟进邮件，发送时间在第一个邮件发送 3 天后"
```
### 分析和报告
```
"显示我所有正在运行的活动的统计数据"
"哪个活动的打开率最高？"
"创建本月活动绩效的摘要报告"
```
## 最佳实践
### 活动管理
1. **从小开始**：在扩大规模之前，先测试 5-10 个潜在客户
2. **监控性能**：定期查看统计数据
3. **尊重限制**：保持在每日注册限制内
4. **A/B 测试**：使用多个邮件版本进行优化
### 潜在客户数据
1. **数据质量**：确保电子邮件地址有效
2. **个性化**：使用有意义的片段和自定义字段
3. **细分**：使用标签和行业组织潜在客户
4. **合规性**：包括取消订阅链接并尊重退出
### AI 代理交互
1. **具体**：为活动创建提供清晰的指示
2. **验证结果**：在运行前检查活动详情
3. **使用示例**：包括示例内容和个性化
4. **监控自动化**：在部署前查看 AI 生成的活动
## 支持
通过 [Woodpecker 支持](https://woodpecker.co/contact-support/) 联系 Woodpecker 支持团队
## 许可证
允许使用此 Docker 镜像用于个人和商业目的。
禁止重新分发、修改和反向工程。
不提供任何保证。
Copyright 2025 Woodpecker.co S.A.
## 可用工具
### 活动管理
#### `createCampaign`
使用基本配置创建活动，包括主题、消息和投递设置。支持使用片段、回退和 spintax 进行个性化内容。
**参数：**
- `name` （字符串）：活动名称
- `subjects` （数组）：电子邮件主题行
- `messages` （数组）：电子邮件正文内容
- `emailAccountIds` （数组）：SMTP 账户 ID
- `timezone` （字符串）：活动时区
- `dailyEnroll` （数字）：每日潜在客户注册限制
- `deliveryDays` （数组）：发送邮件的星期几
- `deliveryTimeStart/Stop` （字符串）：发送时间窗口
- `trackOpens` （布尔值）：启用打开跟踪
#### `createAdvancedCampaign`
使用完整的 API 功能创建活动，包括 A/B 测试和复杂的投递计划。
**参数：**
- `campaignPayload` （字符串）：完整的活动配置 JSON
#### `listCampaigns`
检索活动，可选状态筛选。
**参数：**
- `pageNumber` （数字）：页码（基于 1 的索引）
- `statuses` （数组）：按状态筛选（RUNNING, DRAFT, PAUSED, STOPPED, COMPLETED）
#### `retrieveCampaignDetails`
获取详细的活动结构，包括所有步骤和配置。
**参数：**
- `campaignId` （数字）：活动 ID
#### `retrieveCampaignStatistics`
获取活动性能指标和分析数据。
**参数：**
- `campaignId` （数字）：活动 ID
#### `updateCampaignSettings`
修改活动范围的设置，包括名称、邮箱账户、每日限制和时区。
**参数：**
- `campaignId` （数字）：活动 ID
- `name` （字符串）：活动名称
- `emailAccountIds` （数组）：邮箱账户 ID 列表
- `timezone` （字符串）：活动时区
- `dailyEnroll` （数字）：每日注册限制
#### `buildCampaignUrl`
生成用于访问活动的 Woodpecker 应用 URL。
**参数：**
- `campaignId` （数字）：活动 ID
#### 活动控制
- `runCampaign(campaignId)`：启动活动执行
- `pauseCampaign(campaignId)`：暂停活动
- `stopCampaign(campaignId)`：停止活动
- `deleteCampaign(campaignId)`：完全删除活动
- `makeCampaignEditable(campaignId)`：启用活动修改
### 邮件步骤管理
#### `addStep`
向现有活动添加跟进步骤。
**参数：**
- `campaignId` （数字）：活动 ID
- `payload` （字符串）：步骤配置 JSON
#### `updateCampaignStep`
修改步骤的投递时间和计划。
**参数：**
- `campaignId` （数字）：活动 ID
- `stepId` （字符串）：步骤 ID
- `payload` （字符串）：更新的投递配置
#### `updateStepVersion`
更新电子邮件内容、主题行、签名和跟踪设置。
**参数：**
- `campaignId` （数字）：活动 ID
- `stepId` （字符串）：步骤 ID
- `versionId` （字符串）：版本 ID
- `subject` （字符串）：电子邮件主题
- `message` （字符串）：电子邮件正文（支持 HTML）
- `signature` （字符串）：SENDER 或 NO_SIGNATURE
- `trackOpens` （布尔值）：启用打开跟踪
#### `deleteCampaignStep`
从活动中删除步骤。
**参数：**
- `campaignId` （数字）：活动 ID
- `stepId` （字符串）：步骤 ID
### 潜在客户操作
#### `addProspectsToDatabase`
将新的潜在客户添加到您的全局潜在客户列表中，而不将其纳入任何活动中。
**参数：**
- `prospectsPayload` （字符串）：JSON 数组的潜在客户数据
**注意：**
- 潜在客户被添加到您的账户，但不添加到任何活动中
- 可用于未来的活动注册
- 有助于在创建活动前建立潜在客户数据库
#### `addProspectsToCampaign`
批量添加潜在客户，并包含完整的联系信息和自定义片段。
**参数：**
- `campaignId` （数字）：活动 ID
- `prospectsPayload` （字符串）：潜在客户对象数组
**注意：** 请务必在响应中检查 `DUPLICATE` 潜在客户。如果需要更新数据，请对重复项使用 `updateProspectsInCampaign`。
#### `updateProspectsInDatabase`
更新现有的潜在客户数据库中的潜在客户，或如果他们不存在，则添加新的潜在客户。
**参数：**
- `prospectsPayload` （字符串）：带有更新的潜在客户数据的 JSON 数组
**注意：**
- 现有的潜在客户将根据电子邮件地址进行更新
- 如果电子邮件不存在，则会添加新的潜在客户
- 仅更新要更改的字段
- 更新适用于全局（影响使用这些潜在客户的所有活动）
#### `updateProspectsInCampaign`
更新活动中的现有潜在客户数据（需要明确的用户请求）。
**参数：**
- `campaignId` （数字）：活动 ID
- `prospectsPayload` （字符串）：带有更新的潜在客户对象数组
#### `listProspectsInDatabase`
列出您的全局潜在客户数据库中的潜在客户（与特定活动无关）。
**参数：**
- `pageNumber` （整数）：页码（基于 1 的索引）
**注意：**
- 返回您账户中所有潜在客户的分页结果
- 这些潜在客户可以添加到任何活动中
- 有助于管理您的整体潜在客户数据库
#### `listProspectsInCampaign`
分页检索活动中的潜在客户。
**参数：**
- `campaignId` （数字）：活动 ID
- `pageNumber` （数字）：页码（基于 1 的索引）
#### `searchProspects`
搜索整个数据库中符合特定条件的潜在客户。
**参数：**
- `pageNumber` （整数）：页码（基于 1 的索引）
- `searchCriteria` （对象，可选）：JSON 对象，包含搜索参数
- `filterCriteria` （对象，可选）：JSON 对象，包含额外过滤器
**可用搜索字段：**
- `email` - 电子邮件地址
- `first_name` - 名字
- `last_name` - 姓氏
- `company` - 公司名称
- `organization_id` - 组织 ID
- `industry` - 行业
- `website` - 网站 URL
- `tags` - 标签（区分大小写，无需前缀 #）
- `title` - 职位
- `phone` - 电话号码
- `address` - 街道地址
- `city` - 城市
- `state` - 省/州
- `country` - 国家
- `snippet1` 至 `snippet15` - 自定义字段
**可用过滤字段：**
- `id` - 以逗号分隔的潜在客户 ID 列表
- `status` - 潜在客户的全局状态：ACTIVE, BOUNCED, REPLIED, BLACKLIST, INVALID
- `campaigns_id` - 以逗号分隔的潜在客户参与的活动 ID 列表
- `contacted` - 潜在客户是否曾经被联系过
- `interested` - 兴趣等级：INTERESTED, MAYBE-LATER, NOT-INTERESTED, NOT-MARKED
**注意：**
- 搜索标签时区分大小写，搜索标签时无需添加前缀 #
- 搜索条件对同一字段使用 OR，对不同字段使用 AND
- 要过滤 OPT-OUT 潜在客户，请使用 “BLACKLIST” 状态
- 多个过滤值以逗号分隔
#### `deleteProspects`
永久删除数据库和/或特定活动中的潜在客户。
**参数：**
- `prospectIds` （字符串）：以逗号分隔的要删除的潜在客户 ID 列表
- `campaignIds` （字符串，可选）：要删除潜在客户的活动 ID 列表
**注意：**
- **不带 campaignIds**：从您的整个数据库中删除潜在客户
- **带 campaignIds**：仅从指定的活动中删除潜在客户，同时将其保留在您的全局数据库中
- 此操作是永久的，无法撤销
- 需要明确的用户确认后执行
- 使用从列表/搜索操作中获得的潜在客户 ID（不是电子邮件地址）
**警告：** 全局删除会从所有活动和您的数据库中删除潜在客户。本地删除（使用 campaignIds）仅从指定的活动中删除潜在客户，同时将其保留在您的全局数据库中。
### 账户管理
#### `listMailboxes`
检索可用于活动分配的可用邮箱账户。
**参数：** 无
## 更新日志
### v0.0.9 (2025-07-28)
- 内部改进和错误修复
### v0.0.8 (2025-06-24)
- 添加了全局潜在客户列表工具
### v0.0.7 (2025-06-11)
- 初始发布，包含与活动相关的工具
## 文档
- **Woodpecker API**: [https://developers.woodpecker.co/docs/](https://developers.woodpecker.co/docs/)
- **MCP 协议**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Claude Desktop**: [https://claude.ai/download](https://claude.ai/download)
