Pipedrive CRM

Pipedrive MCP 服务

用于将 Pipedrive CRM 与 Claude Code 和 Claude Desktop 集成的 MCP（Model Context Protocol）服务。可直接通过 AI 助手查询、创建和更新 CRM 数据。

为什么选择此服务

• 优先使用 API v2。 每种实体都使用 Pipedrive 的 v2 REST API（如果有）；仅对没有 v2 对应接口的功能使用 v1（备注、邮件、用户和线索的 CRUD）。请参阅API 版本管理。
• 根据真实 OpenAPI 规范进行契约测试。 请求参数、请求正文和响应结构都会在 tests/contract/ 中，根据随项目提供的 Pipedrive OpenAPI v2 定义（docs/api/openapi-v2.yaml）进行检查，确保 v2 工具不会悄然偏离文档所述的 API。
• 通过实时冒烟测试验证。 工具集会通过真实的 Pipedrive 账户进行广泛测试（scripts/smoke-coverage.ts）；只有无法通过 API 预置数据的功能（例如邮件会话、项目模板）留待手动检查。测试覆盖 Growth+ 套餐限制的端点，例如交易分期（scripts/smoke-installments.ts）。关键写入冒烟测试（例如任务的 is_done 标志）会断言字段值确实已在网络请求中发生变化，而不只是返回 200。
• 由服务端强制执行能力模式。 PIPEDRIVE_MODE 用于选择安全等级——read-only、safe-write（默认：读取 + 非破坏性写入）或 full——不符合当前模式的工具既不会显示在 tools/list 中，直接调用时也会被拒绝。删除、转换和其他不可逆写入（在工具表中以 🔒 标记）需要 full，因此该服务开箱即用时仅支持读取和创建。每个工具还带有 MCP 注解（readOnlyHint/destructiveHint/idempotentHint），让支持策略的客户端能够区分读取、写入和删除操作。请参阅能力模式。
• 采用 MIT 许可，发布时附带 npm 构建来源证明。

如实说明限制。 目前仅支持 STDIO 传输（计划加入 Streamable HTTP 标志），认证使用 Pipedrive API 密钥，这与该服务面向的本地/可自托管层级相匹配。目前尚未提供托管 OAuth 服务。

功能

• 完整的 CRM 操作：交易、人员、组织、活动
• 邮件分析：访问邮件会话和邮件消息，进行互动分析
• 字段发现：将自定义字段哈希码映射为易读名称
• 管道管理：列出管道、阶段和用户
• 分页支持：针对大型数据集的基于游标的分页
• 错误处理：清晰、可执行的错误消息

快速开始

最快的设置方式：npx … init

运行一条命令即可启动引导式安装程序，然后按提示操作。它会打开 Pipedrive API 令牌页面，根据你的账户实时验证密钥，并为你的客户端（Claude Desktop、Claude Code、Cursor、Windsurf 或 VS Code）生成可用的 MCP 配置：

npx -y @ckalima/pipedrive-mcp-server init

它始终会打印可直接粘贴的代码块，还可选择在创建带时间戳的备份后将其写入客户端的配置文件。已提交或共享的配置文件使用 ${PIPEDRIVE_API_KEY} 间接引用，绝不会包含原始密钥。想手动配置？下面的 步骤同样适用。

1. 获取 Pipedrive API 密钥

1. 登录 Pipedrive
2. 前往 设置 > 个人偏好设置 > API
3. 复制你的 API 密钥（40 个字符）

2. 配置 Claude Code

添加到你的 .mcp.json 文件中：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@ckalima/pipedrive-mcp-server"],
      "env": {
        "PIPEDRIVE_API_KEY": "your-40-character-api-key"
      }
    }
  }
}

**包名称：**支持的包是带作用域的 @ckalima/pipedrive-mcp-server。如果你是从引用非带作用域的 pipedrive-mcp-server 的旧代码片段跳转到这里，请将配置更新为上面的带作用域名称——非带作用域名称是另一个无关的包。

你也可以直接启动它，以验证设置：

npx -y @ckalima/pipedrive-mcp-server

或者设置环境变量：

export PIPEDRIVE_API_KEY="your-40-character-api-key"

环境变量

变量	必需	默认值	描述
PIPEDRIVE_API_KEY	是	-	你的 40 位 Pipedrive API 令牌。
PIPEDRIVE_MODE	否	safe-write	服务端强制执行的能力级别：read-only（仅读取）、safe-write（读取 + 非破坏性写入）或 full（所有工具，包括破坏性工具）。超出当前模式的工具会从 tools/list 中隐藏，直接调用时也会被拒绝。设置为可识别的值时，以此为准；空值视为未设置（应用默认值），无法识别的值则回退到 read-only。参见能力模式。
PIPEDRIVE_ENABLE_DESTRUCTIVE	否	false	旧版标志，现已由 PIPEDRIVE_MODE 取代。未设置 PIPEDRIVE_MODE 时，true 会视为 full，其他值均视为 safe-write。为保持向后兼容仍会生效；建议使用 PIPEDRIVE_MODE=full。
PIPEDRIVE_IMAGE_BASE_DIR	否	（未设置）	允许服务读取产品图片的目录，适用于向图片上传工具传入 file_path 的情况。除非设置此项，否则禁用文件系统读取，且 file_path 必须解析到此目录内。如果调用方无法共享服务的文件系统，请保持未设置并传入 base64_data。参见 SECURITY.md。

要启用破坏性工具，请在 .mcp.json 的 env 块中，与 PIPEDRIVE_API_KEY 一起设置 PIPEDRIVE_MODE=full（或为保持向后兼容，设置 PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。低于 full 时，每个 🔒 工具都会返回 DESTRUCTIVE_DISABLED 错误，而不会执行；高于当前级别的工具则会返回 MODE_RESTRICTED 错误。

能力模式

PIPEDRIVE_MODE 用于设置由服务端强制执行的安全级别。该级别通过两种方式强制执行：超出当前模式的工具会从 tools/list 中筛除（因此 Agent 不会看到它们），并且分发器会在处理器运行前按名称拒绝任何超出当前模式的调用，因此该级别是真正的保障，而非 UI 提示。

模式	可用内容	工具数	破坏性操作
read-only	仅读取动词（list/get/search）	69	否
safe-write	读取 + 非破坏性写入	123	否
full	所有工具	155	是

首次设置和评估 Agent 时建议使用：read-only。 先让 Agent 查看数据，确保它不会修改任何内容，再随着信任度提高逐步提升级别。

向后兼容。 设置 PIPEDRIVE_MODE 时，以此为准。未设置时，模式由旧版 PIPEDRIVE_ENABLE_DESTRUCTIVE 标志决定（true → full，否则为 safe-write），因此现有安装升级后会保持原有的执行行为：之前能运行的工具仍然能运行，之前受限的工具仍然受限。未设置时默认级别（safe-write）唯一可观察到的变化是，32 个破坏性工具——之前未启用时执行会被拒绝——现在也会从 tools/list 中隐藏，而不是列出后再拒绝（因此列出的工具数为 123，而不是 155）。无法识别的 PIPEDRIVE_MODE 值会回退到 read-only。

3. 开始使用

配置完成后，Claude 就可以访问你的 Pipedrive 数据：

• “显示金额超过 $10,000 的未结交易”
• “创建一笔名为 'Acme Contract'、金额为 $50,000 的交易”
• “查找 TechCorp 的所有联系人”
• “列出我收件箱中最近的电子邮件会话”
• “交易定义了哪些自定义字段？”

已连接的账户

API 令牌决定你连接的是哪家 Pipedrive 公司，而此前工具结果中没有任何信息说明连接的是哪家。同一客户端中注册两次此服务（例如，一个项目范围的条目和一个读取过期 .env 的本地范围条目）会解析到不同的公司，而优先级较低的那个不会显示出来。现在，服务会在两个位置说明它实际解析到的账户。

启动时，在 stderr 输出一行：

[pipedrive-mcp-server] Connected as [email protected] -> company "Example Corp" (id 12345)

如果检查失败，该行会说明情况（Could not verify connected account: ...），而不是让服务静默启动。如果 API 密钥缺失或格式错误，则会报告账户未经检查，因为没有发出请求。

启动检查完成后收到的第一个工具响应中，会出现一个仅发送一次的 connection 块，其中列出同一家公司的信息，这样 Agent 无需被询问，也无需额外调用工具，就能知道数据来自哪个账户。每个进程只发送一次。检查会在后台运行，因此，若某个工具调用在检查仍进行时完成，响应会原样返回，而该块会出现在之后的某个响应中。请将其视为服务在获知信息后主动提供的一条事实，而不要认为每个早期响应都一定包含它。发送也不等于使用：即使主机原样传递该块，是否采取行动仍由模型决定，而且较小的模型有时会跳过它。

在该块中，company_id 和 verified 由服务断言，并位于顶层。服务无法担保的显示字符串——company_name 和 user_email，或者检查未成功时的 reason——则嵌套在 untrusted_display 下，因为有账户写入权限的任何人都能设置公司名称，而它属于 CRM 内容。如果你解析该块，应将此键下的所有内容视为与 data 相同的信任级别。请参阅 SECURITY.md。

启动时只会发出一次 GET /v1/users/me 请求，超时时间为 10 秒。它不会阻塞启动，也不会导致工具调用失败。不会将任何值与预期值进行比对：verified: true 表示令牌解析到了某个账户，而不表示解析到了正确的账户。

如需按需读取相同信息，请调用 pipedrive_get_current_user，它会返回已连接公司的名称、ID 和域名，以及令牌所有者的用户详情。

*贡献者须知：*横幅行和提示都会包含真实的 Pipedrive 公司 ID。如果你将其中任一内容粘贴到此仓库的文档中，该文档必须放在被 git 忽略的 docs/private/ 中（请参阅 CLAUDE.md），而不是放在公开目录中。

可用工具

155 个工具。 🔒 破坏性操作（需要 PIPEDRIVE_MODE=full，默认关闭） · ⭑ 需要 Growth+ 套餐。当前的能力模式决定了列出哪些工具。

_{本节由 npm run gen:docs 根据实时工具注册表生成。请勿手动编辑——CI 会因内容不一致而失败。}

交易

工具	描述
pipedrive_list_deals	列出 Pipedrive 中的交易，可按负责人、人员、组织、管道、阶段或状态进行筛选。返回分页结果。
pipedrive_get_deal	按 ID 获取特定交易的详细信息，包括所有标准字段和自定义字段。
pipedrive_create_deal	在 Pipedrive 中创建新交易。仅标题为必填项；其他字段均为可选项。
pipedrive_update_deal	更新 Pipedrive 中的现有交易。指定交易 ID 和要更新的字段。
pipedrive_search_deals	按标题文本搜索交易。默认支持模糊匹配。
pipedrive_delete_deal 🔒	删除交易。交易会标记为已删除，并在 30 天后永久移除。
pipedrive_list_deal_followers	列出交易的所有关注者。
pipedrive_add_deal_follower	为交易添加关注者。
pipedrive_delete_deal_follower 🔒	移除交易的关注者。
pipedrive_get_deal_followers_changelog	获取交易关注者的变更记录。
pipedrive_list_deal_products	列出关联到交易的行项目产品。返回分页结果。
pipedrive_add_deal_product	将单个产品作为行项目关联到交易。
pipedrive_update_deal_product	更新关联到交易的行项目产品。所有请求正文中的字段均为可选项。
pipedrive_delete_deal_product 🔒	从交易中移除行项目产品。
pipedrive_bulk_add_deal_products	在一个请求中批量向交易添加最多 100 个行项目产品。
pipedrive_list_deal_discounts	列出应用于交易的所有额外折扣。
pipedrive_add_deal_discount	为交易添加额外折扣。
pipedrive_update_deal_discount	更新交易的额外折扣。除 ID 外，所有字段均为可选项。
pipedrive_delete_deal_discount 🔒	删除交易的额外折扣。
pipedrive_list_deal_installments ⭑	列出一个或多个交易的分期付款。需要提供 deal_ids。需要 Growth+ 套餐。
pipedrive_add_deal_installment ⭑	为交易添加分期付款（付款计划条目）。需要 Growth+ 套餐；该交易必须至少有一个一次性产品，且不得有周期性产品。
pipedrive_update_deal_installment ⭑	更新交易的分期付款。需要 Growth+ 套餐；所有请求正文中的字段均为可选项。
pipedrive_delete_deal_installment 🔒 ⭑	删除交易的分期付款。需要 Growth+ 套餐。
pipedrive_list_archived_deals	列出已归档的交易，筛选条件与活跃交易列表相同（负责人、人员、组织、管道、阶段、状态）。返回分页结果。
pipedrive_convert_deal_to_lead 🔒	将交易转换为潜在客户（异步任务）。破坏性操作：转换成功后，源交易会标记为已删除。返回 conversion_id；转换以异步方式运行，因此必须使用 conversion_id 轮询 pipedrive_get_deal_conversion_status，直至状态终结。需要 PIPEDRIVE_MODE=full（为向后兼容，也可使用 PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_get_deal_conversion_status	获取交易转为潜在客户的转换任务状态。状态约定：'completed'（终结状态，包含 lead_id）、'failed'/'rejected'（终结状态，停止轮询，不会生成潜在客户）、'not_started'/'running'（进行中，需再次轮询）。只有 'completed' 会包含 lead_id，且转换状态会在几天后清除，因此在先前获取到有效状态后返回 404，表示状态已清除（这是停止轮询的终结信号，并非暂时性错误）。请设置有上限的轮询次数（例如最多尝试约 6 次，并采用较短的退避间隔），不要无限循环。

人员

工具	描述
pipedrive_list_persons	列出 Pipedrive 中的人员（联系人），可按负责人、组织或姓名首字母筛选。
pipedrive_get_person	按 ID 获取特定人员的详细信息。
pipedrive_create_person	在 Pipedrive 中创建新人员（联系人）。只需提供姓名。
pipedrive_update_person	更新 Pipedrive 中的现有人员。
pipedrive_search_persons	按姓名、电子邮件或电话号码搜索人员。
pipedrive_delete_person 🔒	删除人员。该人员会被标记为已删除，并在 30 天后永久移除。
pipedrive_list_person_followers	列出某位人员的所有关注者。
pipedrive_add_person_follower	为某位人员添加关注者。
pipedrive_delete_person_follower 🔒	移除某位人员的关注者。
pipedrive_get_person_followers_changelog	获取某位人员的关注者变更记录。
pipedrive_get_person_picture	获取某位人员的图片（只读；返回图片元数据和不同尺寸的图片 URL）。如果该人员没有图片，则返回错误。

组织

工具	描述
pipedrive_list_organizations	列出 Pipedrive 中的组织，可按负责人或名称首字母筛选。
pipedrive_get_organization	按 ID 获取特定组织的详细信息。
pipedrive_create_organization	在 Pipedrive 中创建新组织。只需提供名称。
pipedrive_update_organization	更新 Pipedrive 中的现有组织。
pipedrive_search_organizations	按名称或地址搜索组织。
pipedrive_delete_organization 🔒	删除组织。该组织会被标记为已删除，并在 30 天后永久移除。
pipedrive_list_organization_followers	列出某个组织的所有关注者。
pipedrive_add_organization_follower	为某个组织添加关注者。
pipedrive_delete_organization_follower 🔒	移除某个组织的关注者。
pipedrive_get_organization_followers_changelog	获取某个组织的关注者变更记录。

活动

工具	描述
pipedrive_list_activities	列出 Pipedrive 中的活动，可按负责人、交易、人员、组织、类型或完成状态筛选。
pipedrive_get_activity	按 ID 获取特定活动的详细信息。
pipedrive_create_activity	在 Pipedrive 中创建新活动。必须提供主题和类型。
pipedrive_update_activity	更新 Pipedrive 中的现有活动。可使用此工具将活动标记为已完成。
pipedrive_delete_activity 🔒	删除活动。

备注

工具	描述
pipedrive_list_notes	列出 Pipedrive 中的备注，可按交易、人员、组织或潜在客户筛选。
pipedrive_get_note	按 ID 获取特定备注的详细信息。
pipedrive_create_note	在 Pipedrive 中创建新备注。必须提供内容。可关联交易、人员、组织或潜在客户。
pipedrive_update_note	更新 Pipedrive 中的现有备注。
pipedrive_delete_note 🔒	删除备注。

潜在客户

工具	描述
pipedrive_list_leads	列出 Pipedrive 中未归档的潜在客户，可按负责人、人员或组织进行筛选。
pipedrive_list_archived_leads	列出 Pipedrive 中已归档的潜在客户，可按负责人、人员或组织进行筛选。
pipedrive_get_lead	按 UUID 获取特定潜在客户的详细信息。
pipedrive_create_lead	在 Pipedrive 中创建新的潜在客户。必须提供标题，并关联至少一个 person_id 或 organization_id。
pipedrive_update_lead	更新 Pipedrive 中现有的潜在客户。
pipedrive_search_leads	按标题或关联联系人搜索 Pipedrive 中的潜在客户。
pipedrive_delete_lead 🔒	删除潜在客户。需要设置 PIPEDRIVE_MODE=full（为保持向后兼容，也可设置 PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_convert_lead_to_deal 🔒	将潜在客户转换为交易（Pipedrive v2）。破坏性操作：成功转换后，源潜在客户会被标记为已删除。转换异步运行；此工具会轮询直到转换完成（通常不到 5 秒），并返回新的交易 ID。如果约 30 秒后仍在运行，则返回 conversion_id 和状态，供手动跟进。需要设置 PIPEDRIVE_MODE=full（为保持向后兼容，也可设置 PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_get_lead_conversion_status	按转换 ID 获取异步潜在客户转交易操作的状态（Pipedrive v2 GET /leads/{id}/convert/status/{conversion_id}）。

项目

工具	描述
pipedrive_list_projects	列出 Pipedrive 中的项目，可按看板、阶段或状态进行筛选。返回分页结果。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_get_project	按 ID 获取特定项目的详细信息。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_create_project	在 Pipedrive 中创建新项目。需要提供 title、board_id 和 phase_id。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_update_project	更新 Pipedrive 中现有的项目。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_delete_project 🔒	删除项目。需要设置 PIPEDRIVE_MODE=full（为保持向后兼容，也可设置 PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_search_projects	按标题搜索 Pipedrive 中的项目。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_archive_project	将项目状态设为 archived，以归档项目。（需要 Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_list_project_tasks	列出你已知 ID 的项目任务——仅传入 id（项目 ID）。如需查询范围更广的任务，请使用 pipedrive_list_tasks。（Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_list_project_templates	列出 Pipedrive 中所有可用的项目模板。返回分页结果。
pipedrive_get_project_template	按 ID 获取特定项目模板的详细信息。
pipedrive_list_archived_projects	列出 Pipedrive 中已归档的项目，可按筛选条件、阶段或状态进行筛选。（Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_get_project_permitted_users	获取有权访问项目的用户 ID 列表。返回整数用户 ID 数组。（Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_get_project_changelog	获取项目变更日志，显示变更内容、时间和操作者。返回分页条目，包含 actor_user_id、new_values 和 old_values。 （Projects 附加组件；Projects API 处于公开测试阶段。）

产品

工具	描述
pipedrive_list_products	列出 Pipedrive 中的产品，可按负责人、ID 或筛选条件进行筛选。
pipedrive_get_product	按 ID 获取特定产品的详细信息。
pipedrive_search_products	按名称、代码或自定义字段搜索产品。
pipedrive_create_product	在 Pipedrive 中创建新产品。仅需填写名称。
pipedrive_update_product	更新 Pipedrive 中的现有产品。
pipedrive_delete_product 🔒	删除产品。产品将标记为已删除，并在 30 天后永久移除。
pipedrive_list_product_variations	列出产品的所有变体。
pipedrive_add_product_variation	为产品添加变体。
pipedrive_update_product_variation	更新现有产品变体。
pipedrive_delete_product_variation 🔒	删除产品变体。
pipedrive_list_product_followers	列出产品的所有关注者。
pipedrive_add_product_follower	为产品添加关注者。
pipedrive_delete_product_follower 🔒	移除产品的关注者。
pipedrive_get_product_followers_changelog	获取产品关注者的变更日志。
pipedrive_get_product_image	获取产品图片（返回一张带有公开 URL 的图片，该 URL 有效期为 7 天）。
pipedrive_delete_product_image 🔒	删除产品图片。
pipedrive_upload_product_image	为产品上传图片。通过 file_path 或 base64_data 提供图片，二者必须且只能选择一个。支持 png、jpeg、gif 和 webp。注意：file_path 由 SERVER 进程通过文件系统读取，默认禁用；操作员必须设置 PIPEDRIVE_IMAGE_BASE_DIR，且路径必须解析到该目录内；否则请使用 base64_data，这种方式可安全传输。
pipedrive_update_product_image	更新（替换）产品图片。通过 file_path 或 base64_data 提供图片，二者必须且只能选择一个。支持 png、jpeg、gif 和 webp。注意：file_path 由 SERVER 进程通过文件系统读取，默认禁用；操作员必须设置 PIPEDRIVE_IMAGE_BASE_DIR，且路径必须解析到该目录内；否则请使用 base64_data，这种方式可安全传输。

任务

工具	描述
pipedrive_list_tasks	跨所有项目进行常规任务查询，可选按 project_id、assignee_id、done/milestone 和父级筛选。对于单个项目的完整任务列表以外的查询，请使用此工具。（Projects 插件；Projects API 处于公开测试阶段。）
pipedrive_get_task	按 ID 获取特定任务的详细信息。（Projects 插件；Projects API 处于公开测试阶段。）
pipedrive_create_task	在项目中创建新任务。title 和 project_id 为必填项。使用布尔值 is_done/is_milestone（字段名称与 GET 响应相同）；里程碑任务必须设置 due_date。（Projects 插件；Projects API 处于公开测试阶段。）
pipedrive_update_task	更新现有任务。仅 id 为必填项；其他字段均为可选项。使用布尔值 is_done/is_milestone（字段名称与 GET 响应相同）；里程碑任务必须设置 due_date。（Projects 插件；Projects API 处于公开测试阶段。）
pipedrive_delete_task 🔒	删除任务。如果任务有子任务，这些子任务也会被删除。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。（Projects 插件；Projects API 处于公开测试阶段。）

看板与阶段

工具	描述
pipedrive_list_boards	列出所有项目看板。返回完整列表（不分页——看板端点会一次性返回所有记录）。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_get_board	根据 ID 获取特定项目看板的详细信息。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_create_board	创建新的项目看板。必须提供 name。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_update_board	更新现有项目看板。只需提供 id；其他字段均为可选。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_delete_board 🔒	删除项目看板。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_list_phases	列出项目看板的所有阶段。必须提供 board_id。返回完整列表（不分页——阶段端点会一次性返回某个看板的所有记录）。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_get_phase	根据 ID 获取特定项目阶段的详细信息。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_create_phase	创建新的项目阶段。必须提供 name 和 board_id。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_update_phase	更新现有项目阶段。只需提供 id；其他字段均为可选。设置 board_id 可将此阶段移至其他看板。（Projects 附加组件；Projects API 处于公开测试版。）
pipedrive_delete_phase 🔒	删除项目阶段。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。（Projects 附加组件；Projects API 处于公开测试版。）

邮件

工具	描述
pipedrive_get_person_emails	获取关联到某个人的邮件（公司范围内，包含所有用户的邮件）。返回任意用户邮箱中与此人关联的邮件元数据。注意：如需获取完整邮件正文，请使用 pipedrive_get_mail_message，但仅限您自己邮箱中的邮件。
pipedrive_get_deal_emails	获取关联到某笔交易的邮件（公司范围内，包含所有用户的邮件）。返回任意用户邮箱中与此交易关联的邮件元数据。注意：如需获取完整邮件正文，请使用 pipedrive_get_mail_message，但仅限您自己邮箱中的邮件。
pipedrive_list_mail_threads	仅列出您自己邮箱（已认证用户）中的邮件会话。无法访问其他用户的会话。使用 folder 参数按收件箱、草稿、已发送或归档进行筛选。
pipedrive_get_mail_thread	获取包含邮件的邮件会话。访问权限取决于可见性设置——您有权访问的交易或联系人中的可见会话应该可以正常获取。如果您无权访问该会话，则返回 404。
pipedrive_get_mail_message	获取包含正文的完整邮件。访问权限取决于可见性设置——与您有权访问的交易或联系人关联的邮件应该可以正常获取，即使邮件由其他用户发送。

字段

工具	描述
pipedrive_list_organization_fields	列出所有组织字段定义，包括自定义字段。使用此工具可将 40 字符的字段键映射为易读名称。
pipedrive_list_deal_fields	列出所有交易字段定义，包括自定义字段。对于了解交易数据结构至关重要。
pipedrive_list_person_fields	列出所有人员字段定义，包括自定义字段。用于了解联系人数据结构。
pipedrive_list_product_fields	列出所有产品字段定义，包括自定义字段。
pipedrive_list_project_fields	列出所有项目字段定义，包括自定义字段。（Projects 附加组件；Projects API 处于公开测试阶段。）
pipedrive_get_field	根据字段键获取特定字段的详细信息。可用于查询 40 字符哈希字段键的含义。
pipedrive_create_deal_field	创建交易自定义字段。必须提供 field_name 和 field_type。对于 enum/set 类型，必须提供 options。响应中的 data.field_code 是 40 字符的哈希值，之后更新或删除该字段时必须保留。
pipedrive_update_deal_field	根据 field_code 更新交易自定义字段。无法更改 field_type 和 field_code。
pipedrive_delete_deal_field 🔒	根据 field_code 删除交易自定义字段。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_update_deal_field_options	批量更新交易 enum/set 字段的选项标签。此操作是原子的：如果任何选项 ID 不存在，整个请求都会失败。
pipedrive_delete_deal_field_options 🔒	批量删除交易 enum/set 字段的选项。此操作是原子的：如果任何 ID 不存在，就会失败。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_create_person_field	创建人员自定义字段。必须提供 field_name 和 field_type。对于 enum/set 类型，必须提供 options。响应中的 data.field_code 是 40 字符的哈希值，之后更新时必须保留。
pipedrive_update_person_field	根据 field_code 更新人员自定义字段。无法更改 field_type 和 field_code。
pipedrive_delete_person_field 🔒	删除人员自定义字段。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_update_person_field_options	批量更新人员 enum/set 字段的选项标签。此操作是原子的：如果任何选项 ID 不存在，整个请求都会失败。
pipedrive_delete_person_field_options 🔒	批量删除人员 enum/set 字段的选项。此操作是原子的：如果任何 ID 不存在，就会失败。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_create_organization_field	创建组织自定义字段。必须提供 field_name 和 field_type。对于 enum/set 类型，必须提供 options。响应中的 data.field_code 是 40 字符的哈希值，之后更新时必须保留。
pipedrive_update_organization_field	根据 field_code 更新组织自定义字段。无法更改 field_type 和 field_code。
pipedrive_delete_organization_field 🔒	根据 field_code 删除组织自定义字段。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_update_organization_field_options	批量更新组织 enum/set 字段的选项标签。此操作是原子的：如果任何选项 ID 不存在，整个请求都会失败。
pipedrive_delete_organization_field_options 🔒	批量删除组织 enum/set 字段的选项。此操作是原子的：如果任何 ID 不存在，就会失败。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_create_product_field	创建产品自定义字段。必须提供 field_name 和 field_type。对于 enum/set 类型，必须提供 options。产品字段使用更简单的模型：没有 description、important_fields 或 required_fields。响应中的 data.field_code 是 40 字符的哈希值，之后更新时必须保留。
pipedrive_update_product_field	根据 field_code 更新产品自定义字段。只能更改 field_name 和 ui_visibility（产品字段没有 description/important_fields/required_fields）。
pipedrive_delete_product_field 🔒	根据 field_code 删除产品自定义字段。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_update_product_field_options	批量更新产品 enum/set 字段的选项标签。此操作是原子的：如果任何选项 ID 不存在，整个请求都会失败。
pipedrive_delete_product_field_options 🔒	批量删除产品 enum/set 字段的选项。此操作是原子的：如果任何 ID 不存在，就会失败。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。

流水线和阶段

工具	描述
pipedrive_list_pipelines	使用游标分页列出 Pipedrive 中的销售流水线。流水线包含商机推进所经过的阶段。
pipedrive_list_stages	使用游标分页列出阶段，也可按流水线筛选。阶段代表销售流程中的各个步骤。
pipedrive_get_stage	按 ID 获取特定阶段的详细信息。
pipedrive_create_pipeline	创建新的销售流水线。仅需提供名称。将 is_deal_probability_enabled 设为启用，可为流水线开启加权商机概率。
pipedrive_update_pipeline	更新现有流水线。提供流水线 ID 和要更改的字段。
pipedrive_delete_pipeline 🔒	删除流水线。将流水线标记为已删除。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。
pipedrive_create_stage	在流水线中创建新阶段。必须提供 name 和 pipeline_id。使用 is_deal_rot_enabled 和 days_to_rotten 配置商机过期。
pipedrive_update_stage	更新现有阶段。提供阶段 ID 和要更改的字段。设置 pipeline_id 可将阶段移至其他流水线。
pipedrive_delete_stage 🔒	删除阶段。将阶段标记为已删除。需要设置 PIPEDRIVE_MODE=full（向后兼容：PIPEDRIVE_ENABLE_DESTRUCTIVE=true）。

用户

工具	描述
pipedrive_list_users	列出 Pipedrive 账户中的所有用户。在创建或筛选记录时，可用于查找所有者 ID。
pipedrive_get_user	按 ID 获取特定用户的详细信息。
pipedrive_get_current_user	确认此服务连接到的 Pipedrive 账户：返回已连接公司的信息（名称、ID 和域名），以及 API 密钥所有者的用户详细信息。可用于确认数据来自哪家公司，或获取你的用户 ID。

示例工作流

分析商机流水线

"Show me all open deals in the Sales pipeline, sorted by value"
"Get details for deal 12345 including custom fields"
"Move deal 12345 to the Proposal stage"

客户研究

"Find contacts at Acme Corp"
"Get emails for person 456 to analyze their engagement"
"What custom fields do we have for persons?"

活动管理

"List my overdue activities"
"Create a follow-up call with John Smith for tomorrow at 2pm"
"Mark activity 789 as done"

字段发现

"List all custom fields for deals"
"What does field '8a4d7f...' mean?" (40-char hash)

开发

本地设置

git clone https://github.com/ckalima/pipedrive-mcp-server.git
cd pipedrive-mcp-server
npm install
cp .env.example .env
# Edit .env with your API key

构建和运行

npm run build
npm run start

开发模式

npm run dev

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector node dist/index.js

API 版本管理

此服务同时使用 Pipedrive API 的两个版本，并自动将每次调用路由到正确的版本：

• v2（/api/v2）：商机、联系人、组织、活动、产品、项目、任务、看板和阶段、字段、流水线和阶段，以及线索搜索
• v1（/v1）：邮件、备注、用户，以及线索增删改查

Pipedrive 正在逐步弃用 v1。部分已有 v2 对应版本的 v1 端点将于 2025-12-31 终止服务，预计 v1 将于 2026-07-31 左右全面停止；上述 v1 功能（邮件、备注、用户、线索增删改查）目前尚无 v2 替代方案。详情请参阅 docs/v1-only-capabilities.md。

错误处理

错误会附带可执行的建议：

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or expired",
    "suggestion": "Verify your API key at Pipedrive Settings > Personal preferences > API"
  }
}

常见错误代码：

• MISSING_API_KEY - 设置 PIPEDRIVE_API_KEY 环境变量
• INVALID_API_KEY - 检查 Pipedrive 设置中的 API 密钥
• NOT_FOUND - 请求的资源不存在
• RATE_LIMITED - 等待 60 秒后重试
• VALIDATION_ERROR - 检查请求参数

安全

请参阅 SECURITY.md，了解威胁模型（数据流、凭据处理、提示词注入防护说明、AI/Agent 攻击面目录、运营者最佳实践和已知限制）以及如何私下报告漏洞。简而言之：仅使用 STDIO，不监听网络；API 令牌从环境中读取，绝不会记录到日志中；默认禁用破坏性操作；CRM 工具输出会以结构化方式标记为不可信（这是一种建议性缓解措施，并非保证，详见残余风险说明）。

为了遵循最小权限原则进行部署，请从专用的受限 Pipedrive 用户处生成令牌；除非有需要，否则保持破坏性操作处于禁用状态；并隔离 Agent 的上下文，确保 CRM 数据中的提示词注入没有数据外泄渠道。请参阅 运营者最佳实践。

贡献

请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT - 请参阅 LICENSE

链接

• Pipedrive API 文档
• MCP 协议
• 安全策略
• 报告问题