pipedrive-mcp

pipedrive-mcp

将 Pipedrive CRM 用作 MCP 工具。查找交易、联系人和公司，向其中写入数据，并推动交易在销售管道中流转。

这是一个通过标准输入输出运行 Model Context Protocol 的 Go 单二进制程序，支持从 2026-07-28（当前版本）到 2024-11-05 的协议修订版本，并由客户端协商确定。它作为客户端的子进程在你自己的机器上运行，连接到一个 Pipedrive 工作区：按名称搜索并获取其他操作所需的 ID；读取交易、联系人、组织、活动和备注，以及工作区为自定义字段指定的名称和下拉选项的标签；创建和编辑这些内容，并推动交易在销售管道中流转——赢单、输单、重新打开，或移至其他阶段。

为什么选择 pipedrive-mcp

Pipedrive 自有的 API 分为两套：当前使用的 v2，以及 v1；v1 的弃用日期 2026-07-31 已经过期。本服务采用 v2，只保留 v2 中完全不存在的功能——备注和 whoami 查询。这四个工具依赖的 API 已停止支持；它们目前仍能响应，而且没有可迁移到的 v2 接口，因为 v2 既不提供 /notes，也不提供 /users。这两项例外都在对应的调用位置和 CHANGELOG.md 中进行了说明，因为没人记录下来的 v1 依赖，也就没人会迁移——现在，如果这两项功能中的任何一项返回 410，你会收到注明弃用日期的 [gone]，而不是把问题归咎于请求的验证错误。

它的工具接口遵循已发布的 Google Workspace MCP 服务，而非自行制定一套风格：读取操作保持独立，每项修改都通过一个带有 action 的 manage_ 工具执行，写入操作会说明拒绝原因。模型最可能已经接触过这些服务，因此与之保持一致，就能让本服务无需额外解释也易于理解。

写入操作设有保护，因为 Pipedrive 没有撤销功能。 每次写入前都会先读取目标；除非你明确同意，否则如果某字段已有值，操作就会拒绝覆盖，并逐一指出受到保护的字段。无法采取后续行动的拒绝提示就是一个缺陷。

下方列出的每个工具都在真实的 Pipedrive 工作区和测试所用的模拟环境中运行过，覆盖读取、资源、保护性拒绝、演练路径，以及对每种可逆资源执行的一项可撤销写入。如今，这套测试已成为 Go 测试套件的一部分，而非依赖惯例：它位于带有 -tags=integration 的 internal/integration/ 中，由 make integration 运行。仍有两项限制。写入探测除了标签外还需要额外启用 PIPEDRIVE_INTEGRATION_WRITES=1，因此不设置该项的运行只能验证读取部分——是否向在线 CRM 写入数据应由人决定，而不应默认执行。其次，这些测试只在一个工作区中运行过，因此与该工作区不同的自定义字段或权限配置尚未经过测试。

安装

go install github.com/mmedum/pipedrive-mcp/cmd/pipedrive-mcp@latest

这会将二进制文件安装到 Go 的 bin 目录，而该目录通常不在你的 PATH 中。如果下一条命令提示 command not found，可以使用完整路径，或将该目录添加一次：

"$(go env GOPATH)/bin/pipedrive-mcp" --version    # check it landed
export PATH="$(go env GOPATH)/bin:$PATH"          # or add it to your shell profile

也可以从最新版本下载签名压缩包——适用于 Linux、macOS 和 Windows，支持 amd64 和 arm64——然后将二进制文件放到你的 PATH 中。无需盲目信任任何发布版本：

# One signature over the checksum file, keyless, tied to the release
# workflow's own identity on a tag. Check it first: until it passes, the
# checksums are only what the release says now.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github\.com/mmedum/pipedrive-mcp/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

# --ignore-missing, because checksums.txt covers every archive and every
# SBOM, and you will have downloaded one of them. On macOS, use
# shasum -a 256 -c in place of sha256sum -c.
sha256sum -c checksums.txt --ignore-missing

# And the archive itself carries build provenance.
gh attestation verify pipedrive-mcp_X.Y.Z_linux_amd64.tar.gz --owner mmedum

设置 Pipedrive

服务会将 API 令牌存储在 操作系统密钥环中（Linux 上为 libsecret，macOS 上为 Keychain，Windows 上为 Credential Manager），而不是要求你将令牌粘贴到 JSON 配置中。完整参考和验证规则：docs/configuration.md。

pipedrive-mcp login
# Pipedrive workspace subdomain (e.g. acme for acme.pipedrive.com): your-subdomain
# Pipedrive API token for "your-subdomain": ········
# login: token stored in OS keyring (service=pipedrive-mcp, account=your-subdomain)
# login: default domain recorded in ~/.config/pipedrive-mcp/config.json

传入 --domain your-subdomain（或设置 PIPEDRIVE_COMPANY_DOMAIN）即可跳过域名提示，适用于脚本。

之后，你的 MCP 客户端配置无需包含工作区域名或令牌——两者都会从密钥环和一个小型非机密指针文件（os.UserConfigDir()/pipedrive-mcp/config.json）中解析。运行 pipedrive-mcp status 进行验证，或运行 pipedrive-mcp logout 清除它们。

如需在一个 Shell 会话中覆盖记录的域名（例如临时指向其他工作区），请设置 PIPEDRIVE_COMPANY_DOMAIN——环境变量的优先级高于 userconfig 指针。对于 CI、自动化或临时使用其他令牌，请设置 PIPEDRIVE_API_TOKEN。环境变量的优先级高于密钥环，与 gh 和 aws CLI 一致。

连接客户端

Claude Desktop

在 pipedrive-mcp login 将令牌存入密钥环并在用户配置中记录默认域名后，Claude Desktop 配置无需包含任何内容——既不需要密钥，也不需要域名：

{
  "mcpServers": {
    "pipedrive": {
      "command": "/usr/local/bin/pipedrive-mcp"
    }
  }
}

如需固定到特定工作区（例如，你存储了多个工作区时），请在 env 下添加 PIPEDRIVE_COMPANY_DOMAIN，仅覆盖此 MCP 服务记录的默认域名。

配置

每项设置都是 PIPEDRIVE_* 环境变量。完整列表、默认值和验证规则见 docs/configuration.md。以下设置会改变服务的行为：

环境变量	必填	默认值	用途
PIPEDRIVE_COMPANY_DOMAIN	仅在未使用 login 时	—	子域名（例如，acme.pipedrive.com 中的 acme）。运行 pipedrive-mcp login 后，域名会记录在用户配置中，不再需要通过环境变量设置。
PIPEDRIVE_API_TOKEN	否	—	CI/自动化的备用方式。交互式使用时，建议运行 pipedrive-mcp login。
LOG_LEVEL	否	info	debug / info / warn / error。
LOG_FORMAT	否	text	text / json。
PIPEDRIVE_DRY_RUN	否	false	服务级别的 dry-run 下限：所有写入操作都会变为演练。单次调用的 dry_run 只能启用演练，不能关闭。
PIPEDRIVE_HTTP_TIMEOUT	否	30s	每次请求的出站 HTTP 超时时间。

工具

共有 20 个工具。读取操作各自独立，所有变更都通过一个带有 action 的 manage_ 工具完成，Google Workspace MCP 服务也是这样设计的。

从 search 开始。 它是自然语言入口：将名称转换为其他工具所需的数字 ID。想查找“Acme 交易”时使用 list_deals 是常见错误——它只会筛选，不会匹配名称。

工具	功能
search	在交易、人员、组织、产品、文件和潜在客户中进行全文搜索——将名称转换为 ID 的途径
whoami	查询令牌代表哪个账户、指向哪个工作区，以及活动到期时间所用的时区
get_deal	获取一笔交易：金额、币种、状态、阶段、关联人员和公司，以及以工作区名称显示的自定义字段，下拉选项显示为标签
list_deals	按状态、销售流程、阶段、负责人、人员、组织或更新时间范围列出交易，使用游标分页。已归档的交易位于独立集合中——传入 archived
manage_deal	创建或编辑交易、将其移至其他阶段、关闭、归档或删除——create、update、move_stage、mark_won、mark_lost、reopen、archive、unarchive、delete。自定义字段按名称指定，下拉选项按标签指定
get_person	获取一位联系人：姓名、所有带标签的邮箱和电话号码、所属公司以及自定义字段
list_persons	按负责人、关联组织或更新时间范围列出人员，使用游标分页
manage_person	创建、编辑或删除联系人——create、update、delete。使用 name 或 first_name/last_name 指定姓名，不能同时使用两者。自定义字段按名称指定，下拉选项按标签指定
get_organization	获取一家公司：Pipedrive 解析的地址、关联人员数量以及自定义字段
list_organizations	按负责人或更新时间范围列出公司，使用游标分页
manage_organization	创建、编辑或删除公司——create、update、delete。自定义字段按名称指定，下拉选项按标签指定
get_activity	获取一项通话、电子邮件、会议或任务，包括其地点、参与者和会议详情
list_activities	按状态、负责人、交易、人员、组织、潜在客户或更新时间范围列出活动；除非特别要求，否则不返回备注
manage_activity	创建或编辑活动、将其标记为完成或删除——create、update、complete、reopen、delete
get_note	获取一条备注：其 HTML、作者以及关联的记录
list_notes	按关联记录、作者、日期范围或更新时间范围列出备注
manage_note	创建、编辑或删除备注——create、update、delete
list_pipelines	列出令牌可见的所有销售流程；不分页，工作区很少会有 20 个
list_stages	列出某个销售流程的阶段，以及 Pipedrive 为每个阶段设置的交易概率
refresh_field_cache	在有人通过 Pipedrive UI 添加、重命名或扩展自定义字段后，重新读取自定义字段名称和下拉选项标签

受保护的写入

Pipedrive 不支持撤销，因此拒绝是唯一的防护手段。每个 manage_ 工具都会在写入前读取目标，并拒绝那些会破坏你无法查看的数据的写入。每次拒绝都会说明两件事：它要保护的字段，以及允许写入的参数——无法采取行动的拒绝就是一个 Bug。

• dry_run 会报告写入会查找和更改哪些内容，但不会发送任何内容。
• overwrite 会列出更新可能替换的字段，例如 ["title", "value"]，与拒绝信息中列出的内容完全一致。列出的字段少于拒绝信息中的字段，仍会因遗漏的字段而被拒绝，因此，同意替换标题并不代表同意替换值。填入空字段不会破坏任何内容，也不需要许可。
• expect_version 会携带从为本次写入提供依据的读取操作中获取的 update_time；如果记录自那时起发生了变化，就会拒绝写入。这只是尽力而为：Pipedrive 不支持 compare-and-set，因此它能捕获并发编辑，但无法避免蓄意制造的竞态。

这些指定的状态转换——mark_won、mark_lost、move_stage、reopen、archive、unarchive 和 complete——不接受 overwrite，因为它们更改的字段正是你指定的字段。没有任何操作会故意成为单向门：reopen 可以撤销交易的 mark_won 和 mark_lost，也可以撤销活动的 complete。但它不会清除交易的 lost_reason——Pipedrive 只接受在已流失的交易上设置该字段，因此，上次流失的文本会保留在记录中，直到交易再次流失并设置新的原因。例外是 manage_note 的 delete，它执行的是软删除——Pipedrive v1 会清除 active_flag，get_note 仍会返回该备注，并且此处没有任何操作会将该标记设回去。

被阻止的受保护写入会带有 [refused] 标签返回；这是专属的错误类别，模型可以据此区分验证失败和上游错误。一种情况重试毫无用处，另一种情况重试才是正确做法。

资源

五个资源模板与 get_ 工具相对应，供附加记录而非调用工具的客户端使用：

pipedrive://deals/{id}          pipedrive://organizations/{id}
pipedrive://persons/{id}        pipedrive://activities/{id}
pipedrive://notes/{id}

它们与工具共用相同的代码，因此两者不会对同一记录产生不同的描述。URI 无法携带工具的选项——include_attendees、include_notes——因此仍需使用工具。

此处未涵盖的内容

稳定的接口只兑现了半个承诺，另一半就是这份清单。以下内容都不是遗漏，无需报告；每一项都是经过权衡的决定或 API 限制。

没有对应工具的资源。 产品、线索、文件、项目和目标各自都是一个里程碑。search 可以找到产品、文件和线索——其 item_type 涵盖这些类型——因此你可以把名称转换为 ID，然后就无从继续操作了，最好在尝试之前了解这一点。

完全未建模的资源，且不计划在 1.x 中支持：webhook、邮件和邮件线程、订阅和经常性收入、已保存的筛选器、货币、交易转化为线索、关注者、作为受管理关系的交易参与者，以及创建或修改自定义字段定义（字段值可读写，但定义不可）。

这里不支持合并记录。 Pipedrive 可以合并两个人员或两个组织；此服务不能。原因在于安全防护约定，而非 API 限制——合并会丢弃一条记录的字段值，改用另一条记录的值，而且调用方尚未读取这两条记录，因此无法拒绝并说明即将丢失的内容。

字段一旦有值就无法清空——Pipedrive v2 会拒绝 null，并将空字符串存储为一个值，因此字段可以更改，但无法清空。

API 本身无法做到的两件事，重试也无济于事：无法在服务端筛选活动类型（先请求记录，再按其 type 筛选），且 search 不会索引活动（请通过 list_activities 获取）。

Pipedrive 的搜索索引会保留已删除的记录，返回时却不会标明这一点——已删除的组织会无限期留在索引中，已删除的人员则会在删除后一段时间内留在索引中。因此，search 会将搜索结果与 /organizations 和 /persons 的结果进行核对，并剔除已不存在的记录：每页中每种类型额外调用一次；如果某页不含这两种类型，则不调用。交易不会进行核对，因为 /deals 会排除已归档的交易——而已归档的交易仍然有效——因此核对会误删有效记录；Pipedrive 会从自己的索引中剔除已删除的交易。产品、文件和线索会原样返回，不进行核对，因为此处没有可用于核对的 list_ 工具。由于剔除操作发生在 Pipedrive 分页之后，返回的页面可能条目不足，或为空但仍设置了 next_cursor：空页面并不代表结束。

有四个工具使用 Pipedrive API v1，该版本已过停用日期——get_note、list_notes、manage_note 和 whoami，因为 v2 没有 /notes 和 /users。它们明确不在 1.0 兼容性承诺范围内；请参阅 CHANGELOG.md。

安全性

• 每次写入都会在调用时进行防护。 dry_run 会报告写入将查找和更改的内容，但不会发送任何内容。更新已存在的内容前必须提供 overwrite，而 expect_version 会拒绝修改自读取后发生变化的记录。注册不再是门槛：不存在的工具无法解释自己为何不会执行操作，因此由拒绝操作本身来说明。
• PIPEDRIVE_DRY_RUN 是底线，不是默认值。 每个写入工具都会遵守它。单次调用中的 dry_run 可以为一次写入启用预演；只要设置了该标志，任何线上参数都无法关闭预演，因此“设置后服务端就无法写入”始终成立，无论模型提出什么请求。
• 标准输出仅承载 MCP JSON-RPC 帧。 这是 MCP stdio 传输自身的规则，并由 forbidigo 强制执行：进程的流只在 main 中命名，其他地方都不会命名。任何意外打印都会破坏数据流，客户端会悄然停止工作。
• 拼错的子命令会以非零状态码退出，而不是启动服务后报告成功。

工作原理

MCP client ──stdio──► pipedrive-mcp
                       ├── tools       one handler per tool; shapes the reply
                       ├── server      SDK wiring and the registered surface
                       ├── pipedrive   REST client for the v2 and v1 APIs
                       ├── config      every setting, from environment and flags
                       ├── credentials the API token: keyring, file, environment
                       └── userconfig  the non-secret profile

获取帮助

运行 pipedrive-mcp status。它会显示解析出的工作区、域名的来源、是否找到令牌以及令牌所在的存储位置，还会显示启动时的身份验证探测是否成功连接到 Pipedrive——这些涵盖了首次运行时大多数常见问题。status --json 会将相同信息打印为一个 JSON 对象，供需要在启动服务前判断该服务是否已获授权的脚本使用；应根据 credentials.resolved 字段进行分支判断，probe.ran 则可区分检查是被跳过还是失败。数据结构见docs/configuration.md。

除此之外，以下问题值得了解：

• 启动时出现 401 Unauthorized，并立即退出。 API 令牌无效、已撤销，或属于错误的工作区。修正令牌后重启；服务不会在进程运行期间轮询令牌变更。
• 找不到 custom_field "Region"。 缓存已过期。调用 refresh_field_cache 工具，即可在不重启服务的情况下并行重新获取交易 / 个人 / 组织字段元数据。
• 大模型的行为出乎意料。 MCP 传输不会携带用户的提示词，因此服务日志无法告诉你大模型调用工具的原因。将 stderr 中的请求 ID 与 MCP 客户端的提示词日志关联起来，即可还原调用意图。

运行手册和运维指南：docs/operations.md。

如果这些内容仍无法解释问题，请提交 issue。切勿在 issue 中粘贴 API 令牌、公司域名或记录内容；请改为描述其结构。安全问题请通过 SECURITY.md 私下报告。

版本管理

工具名称、参数及输出结构在同一主版本内保持稳定。这项承诺自 1.0.0 起生效：现在要进行破坏性变更必须提升主版本；而在 1.0.0 之前，小版本发布仍可能调整工具接口。需要你采取操作的变更——例如工具重命名、参数变更或客户端配置中的命令变更——会在 CHANGELOG.md 中标记为 BREAKING，发布说明也由此生成。哪些版本会获得修复，详见 SECURITY.md。

开发

make build     # the binary
make test      # race detector, per-package coverage floor
make check     # everything CI runs
make smoke     # drive the built binary over stdio and read the reply

make check 定义了完成标准：gofmt、go vet、golangci-lint、达到每个包覆盖率下限的竞态测试、govulncheck、许可证白名单、泄漏检查关卡（拒绝工作树中任何看起来像真实账户数据的内容）、固定版本检查关卡（要求每个 action 都固定到提交 SHA，且安装的每个工具都固定到确切版本）、依赖项固定版本的过期检查关卡、清单检查关卡（要求可安装的打包内容符合其 schema、打包器暂存的文件、服务自身的设置，以及由该系列六个归档文件及其名称组成的发布内容），针对变更日志版本标题的链接检查关卡，以及 stdio 冒烟测试。CI 还会与基准分支进行 schema 差异检查，若工具接口发生未经确认的变更则失败；也会检查变更日志，若源代码发生变更但 [Unreleased] 下没有相应条目则失败。

惯例见 CONTRIBUTING.md；构建、测试和发布说明见 docs/development.md 和 docs/release.md。

文档

• docs/architecture.md — 设计、相关依据和阶段计划。
• docs/configuration.md — 所有设置。
• docs/development.md — 构建和测试。
• docs/operations.md — 实际运行指南。
• docs/release.md — 发布流程。
• docs/security.md — 威胁模型。

贡献

• CONTRIBUTING.md — PR 流程、检查关卡清单、Phase 0 试验清单、沙盒账户所有权。
• docs/development.md — 本地运行指南：先决条件、make check、基于沙盒的端到端验证、Claude Desktop 配置。

安全

• 报告漏洞前，请先阅读 SECURITY.md。
• 有关令牌处理和威胁模型，请阅读 docs/security.md。

行为准则

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

许可证

Apache License 2.0。