pipedrive-automation

通过 Rube MCP 自动化 Pipedrive

通过 Composio 的 Pipedrive 工具包自动化 Pipedrive CRM 工作流，包括交易管理、联系人和组织操作、活动安排、备注，以及管道／阶段查询。

工具包文档：composio.dev/toolkits/pipedrive

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Pipedrive 连接，并使用工具包 pipedrive
• 始终先调用 RUBE_SEARCH_TOOLS 获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 pipedrive 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请通过返回的授权链接完成 Pipedrive OAuth
4. 确认连接状态显示为 ACTIVE，然后再运行任何工作流

核心工作流

1. 创建和管理交易

适用场景：用户想要创建新交易、更新现有交易，或查看销售管道中的交易详情。

工具调用顺序：

1. PIPEDRIVE_SEARCH_ORGANIZATIONS - 查找要关联到交易的现有组织 [可选]
2. PIPEDRIVE_ADD_AN_ORGANIZATION - 如果未找到组织，则创建组织 [可选]
3. PIPEDRIVE_SEARCH_PERSONS - 查找要关联的现有联系人 [可选]
4. PIPEDRIVE_ADD_A_PERSON - 如果未找到联系人，则创建联系人 [可选]
5. PIPEDRIVE_GET_ALL_PIPELINES - 获取管道 ID [前置条件]
6. PIPEDRIVE_GET_ALL_STAGES - 获取管道中的阶段 ID [前置条件]
7. PIPEDRIVE_ADD_A_DEAL - 使用标题、金额、org_id、person_id 和 stage_id 创建交易 [必需]
8. PIPEDRIVE_UPDATE_A_DEAL - 创建后修改交易属性 [可选]
9. PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL - 添加订单项／产品 [可选]

关键参数：

• title：交易标题（创建时必需）
• value：交易金额
• currency：3 个字母的 ISO 货币代码（例如，“USD”）
• pipeline_id / stage_id：用于确定管道位置的数字 ID
• org_id / person_id：关联组织和联系人
• status：“open”、“won”或“lost”
• expected_close_date：格式为 YYYY-MM-DD

注意事项：

• title 是 PIPEDRIVE_ADD_A_DEAL 唯一必需的字段；其他字段均为可选
• 自定义字段在响应中会显示为较长的哈希键；使用 dealFields 端点进行映射
• PIPEDRIVE_UPDATE_A_DEAL 需要交易的数字 id
• 将 status 设为“lost”时，还必须提供 lost_reason

2. 管理联系人（个人和组织）

使用场景：用户想在 Pipedrive 中创建、更新、搜索或列出联系人和公司。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS - 按姓名、电子邮件或电话号码搜索现有个人 [前置步骤]
2. PIPEDRIVE_ADD_A_PERSON - 如果未找到，则创建新联系人 [必需]
3. PIPEDRIVE_UPDATE_A_PERSON - 修改现有联系人的详细信息 [可选]
4. PIPEDRIVE_GET_DETAILS_OF_A_PERSON - 获取完整的联系人记录 [可选]
5. PIPEDRIVE_SEARCH_ORGANIZATIONS - 搜索现有组织 [前置步骤]
6. PIPEDRIVE_ADD_AN_ORGANIZATION - 如果未找到，则创建新组织 [必需]
7. PIPEDRIVE_UPDATE_AN_ORGANIZATION - 修改组织属性 [可选]
8. PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION - 获取完整的组织记录 [可选]

关键参数：

• name：创建个人和组织时均为必填项
• email：由包含 value、label、primary 字段的对象组成的数组，适用于个人
• phone：由包含 value、label、primary 字段的对象组成的数组，适用于个人
• org_id：将个人关联到组织
• visible_to：1 = 仅所有者可见，3 = 整个公司可见
• term：SEARCH_PERSONS / SEARCH_ORGANIZATIONS 的搜索词（至少 2 个字符）

注意事项：

• PIPEDRIVE_ADD_AN_ORGANIZATION 可能会与现有组织自动合并；请检查 response.additional_data.didMerge
• 电子邮件和电话号码字段是对象数组，而非普通字符串：[{"value": "[email protected]", "label": "work", "primary": true}]
• PIPEDRIVE_SEARCH_PERSONS 不支持 * 或 @ 等通配符；请使用 PIPEDRIVE_GET_ALL_PERSONS 列出所有个人
• 通过 PIPEDRIVE_DELETE_A_PERSON 或 PIPEDRIVE_DELETE_AN_ORGANIZATION 删除属于软删除，数据会保留 30 天，之后永久删除

3. 安排和跟踪活动

使用场景：用户想创建与交易、联系人或组织关联的电话、会议、任务或其他活动。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS 或 PIPEDRIVE_GET_DETAILS_OF_A_DEAL - 获取关联实体的 ID [前置步骤]
2. PIPEDRIVE_ADD_AN_ACTIVITY - 使用主题、类型和到期日创建活动 [必需]
3. PIPEDRIVE_UPDATE_AN_ACTIVITY - 修改活动详情或将活动标记为已完成 [可选]
4. PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY - 获取活动记录 [可选]
5. PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER - 列出用户的活动 [可选]

关键参数：

• subject：活动标题（必填）
• type：活动类型键字符串，例如 "call"、"meeting"、"task"、"email"（必填）
• due_date：格式为 YYYY-MM-DD
• due_time：格式为 HH:MM
• duration：格式为 HH:MM（例如，"00:30" 表示 30 分钟）
• deal_id / person_id / org_id：关联相关实体
• done：0 = 未完成，1 = 已完成

注意事项：

• PIPEDRIVE_ADD_AN_ACTIVITY 的 subject 和 type 均为必填项
• type 必须与账户中现有 ActivityTypes 的 key_string 匹配
• done 是整数（0 或 1），不是布尔值
• 响应的 additional_data 中包含 more_activities_scheduled_in_context

4. 添加和管理备注

使用场景：用户想为交易、人员、组织、潜在客户或项目添加备注。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS 或 PIPEDRIVE_GET_DETAILS_OF_A_DEAL - 解析实体 ID [前置条件]
2. PIPEDRIVE_ADD_A_NOTE - 创建包含 HTML 内容并关联实体的备注 [必需]
3. PIPEDRIVE_UPDATE_A_NOTE - 修改备注内容 [可选]
4. PIPEDRIVE_GET_ALL_NOTES - 按实体筛选并列出备注 [可选]
5. PIPEDRIVE_GET_ALL_COMMENTS_FOR_A_NOTE - 获取备注上的评论 [可选]

关键参数：

• content：HTML 格式的备注正文（必需）
• deal_id / person_id / org_id / lead_id / project_id：必须至少关联一个实体
• pinned_to_deal_flag / pinned_to_person_flag：列出备注时筛选已置顶的备注

注意事项：

• content 为必需参数，支持 HTML；纯文本也可使用，但会在服务端进行清理
• 必须提供 deal_id、person_id、org_id、lead_id 或 project_id 中的至少一个
• PIPEDRIVE_GET_ALL_NOTES 默认返回所有实体的备注；使用实体 ID 参数进行筛选

5. 查询销售管道和阶段

使用场景：用户想查看销售管道、阶段，或管道／阶段中的交易。

工具调用顺序：

1. PIPEDRIVE_GET_ALL_PIPELINES - 列出所有管道及其 ID [必需]
2. PIPEDRIVE_GET_ONE_PIPELINE - 获取特定管道的详情和交易摘要 [可选]
3. PIPEDRIVE_GET_ALL_STAGES - 列出所有阶段，可按管道筛选 [必需]
4. PIPEDRIVE_GET_ONE_STAGE - 获取特定阶段的详情 [可选]
5. PIPEDRIVE_GET_DEALS_IN_A_PIPELINE - 列出管道中各阶段的所有交易 [可选]
6. PIPEDRIVE_GET_DEALS_IN_A_STAGE - 列出特定阶段中的交易 [可选]

关键参数：

• id：管道或阶段 ID（单项端点必需）
• pipeline_id：按管道筛选阶段
• totals_convert_currency：3 位货币代码，或用于转换后总额的 "default_currency"
• get_summary：设为 1，以在管道响应中获取交易摘要

注意事项：

• PIPEDRIVE_GET_ALL_PIPELINES 不接受参数；会返回所有管道
• 除非指定 pipeline_id，否则 PIPEDRIVE_GET_ALL_STAGES 会返回所有管道的阶段
• 仅当设置了 totals_convert_currency 时，管道摘要中的交易计数才会使用 per_stages_converted

常见模式

ID 解析

操作前，始终先将显示名称解析为数字 ID：

• 组织名称 -> org_id：使用 term 参数调用 PIPEDRIVE_SEARCH_ORGANIZATIONS
• 人员姓名 -> person_id：使用 term 参数调用 PIPEDRIVE_SEARCH_PERSONS
• 管道名称 -> pipeline_id：调用 PIPEDRIVE_GET_ALL_PIPELINES，然后按名称匹配
• 阶段名称 -> stage_id：使用 pipeline_id 调用 PIPEDRIVE_GET_ALL_STAGES，然后按名称匹配

分页

大多数列表端点使用基于偏移量的分页：

• 使用 start（偏移量）和 limit（每页大小）参数
• 检查 additional_data.pagination.more_items_in_collection，以确定是否还有更多页面
• 使用 additional_data.pagination.next_start 作为下一页的 start 值
• 某些端点的默认 limit 约为 500；为确保分页行为可预测，请显式设置该参数

已知注意事项

ID 格式

• 所有实体 ID（交易、人员、组织、活动、管道、阶段）均为整数
• 潜在客户 ID 是 UUID 字符串，而非整数
• 自定义字段键是较长的字母数字哈希值（例如 "a1b2c3d4e5f6..."）

速率限制

• Pipedrive 对每家公司实施 API 速率限制；批量操作应控制调用频率
• PIPEDRIVE_GET_ALL_PERSONS 和 PIPEDRIVE_GET_ALL_ORGANIZATIONS 可能返回大型数据集；请始终使用分页

参数注意事项

• 人员的 Email 和电话是对象数组，而不是普通字符串
• visible_to 是数值：1 = 仅所有者可见，3 = 整个公司可见，5 = 特定群组可见
• 活动中的 done 是整数 0/1，而不是布尔值 true/false
• 创建组织时，重复项可能会被自动静默合并；请检查响应中的 didMerge
• PIPEDRIVE_SEARCH_PERSONS 要求至少 2 个字符，且不支持通配符

响应结构

• 自定义字段会以哈希键的形式出现在响应中；请通过相应的 Fields 端点映射这些字段
• 在封装执行中，响应数据通常嵌套在 response.data.data 下
• 搜索结果位于 response.data.items 下，而非顶层

快速参考

任务	工具标识	关键参数
创建交易	PIPEDRIVE_ADD_A_DEAL	title、value、org_id、stage_id
更新交易	PIPEDRIVE_UPDATE_A_DEAL	id、status、value、stage_id
获取交易详情	PIPEDRIVE_GET_DETAILS_OF_A_DEAL	id
搜索人员	PIPEDRIVE_SEARCH_PERSONS	term、fields
添加人员	PIPEDRIVE_ADD_A_PERSON	name、email、phone、org_id
更新人员	PIPEDRIVE_UPDATE_A_PERSON	id、name、email
获取人员详情	PIPEDRIVE_GET_DETAILS_OF_A_PERSON	id
列出所有人员	PIPEDRIVE_GET_ALL_PERSONS	start、limit、filter_id
搜索组织	PIPEDRIVE_SEARCH_ORGANIZATIONS	term、fields
添加组织	PIPEDRIVE_ADD_AN_ORGANIZATION	name、visible_to
更新组织	PIPEDRIVE_UPDATE_AN_ORGANIZATION	id、name、address
获取组织详情	PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION	id
添加活动	PIPEDRIVE_ADD_AN_ACTIVITY	subject、type、due_date、deal_id
更新活动	PIPEDRIVE_UPDATE_AN_ACTIVITY	id、done、due_date
获取活动详情	PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY	id
列出分配给特定用户的活动	PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER	user_id、start、limit
添加备注	PIPEDRIVE_ADD_A_NOTE	content、deal_id 或 person_id
列出备注	PIPEDRIVE_GET_ALL_NOTES	deal_id、person_id、start、limit
列出销售管道	PIPEDRIVE_GET_ALL_PIPELINES	（无）
获取销售管道详情	PIPEDRIVE_GET_ONE_PIPELINE	id
列出阶段	PIPEDRIVE_GET_ALL_STAGES	pipeline_id
销售管道中的交易	PIPEDRIVE_GET_DEALS_IN_A_PIPELINE	id、stage_id
阶段中的交易	PIPEDRIVE_GET_DEALS_IN_A_STAGE	id、start、limit
向交易添加产品	PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL	id、product_id、item_price

---

由 Composio 提供支持