mcp-pipedrive

Pipedrive MCP 服务

最完整、最稳健的 Pipedrive MCP 实现，适用于 Claude

一个可用于生产环境的 Model Context Protocol 服务，可让 Claude 全面访问 Pipedrive CRM API。此服务支持通过自然语言对话，无缝自动化销售工作流、商机管理、联系人整理和活动跟踪。

由 Nubiia 构建并维护——为企业提供 AI 自动化和集成服务（MCP、Holded、Pipedrive 等）。想为你的企业打造类似的服务？欢迎通过 nubiia.es 联系我们。

功能

• 涵盖 29 个类别的 300 多个工具 - 完整覆盖整个 Pipedrive REST API（v1 + v2）
• 高级速率限制 - 每秒 10 个请求，突发容量最高可达 100 个请求
• 多级缓存 - 常用数据的 TTL 为 5-15 分钟
• 重试逻辑 - 失败请求采用指数退避（429、500、502、503、504）
• 全面的错误处理 - 提供详细的错误消息和可执行的建议
• 完整的 TypeScript 支持 - 全面提供类型安全的架构和接口
• Zod 验证 - 对所有输入进行运行时验证，并提供有用的错误消息
• MCP 资源 - 只读访问管道、自定义字段和用户信息
• MCP 提示词 - 为常见操作提供 5 个引导式工作流
• 性能指标 - 内置请求时长和成功率跟踪
• 只读模式 - 可选的安全模式，可阻止所有写入操作
• 工具集筛选 - 根据需要启用或禁用特定工具类别

工具类别

307 个工具涵盖 29 个类别——完整覆盖 Pipedrive REST API（v1 + v2）：

类别	工具数	描述
交易	43	完整生命周期：CRUD、阶段、参与者、产品、文件、合并、转换、分期付款（v2）
字段	30	自定义字段发现 + 交易/人员/组织/产品/项目字段的 CRUD，以及线索和备注字段
人员	23	联系人管理，包括自定义字段、活动、交易、文件和关注者
组织	21	公司管理，以及与人员、交易和活动的关系
项目	16	项目、看板、阶段、群组、任务和计划管理
管道	15	管道管理、阶段、转换和流转统计
线索	15	线索 CRUD、标签、来源、搜索，以及线索↔交易转换
角色	14	角色、分配、设置和管道可见性
产品	13	产品目录、交易/人员附件、文件和关注者
用户	12	用户、权限、关注者和角色分配
备注	9	交易、人员和组织的备注与评论
活动	9	任务、通话和会议安排，支持截止日期和完成状态
系统	9	健康状态、指标、货币、用户设置、最近项目和缓存
团队	8	团队管理和成员管理
文件	7	文件上传、下载、管理和远程文件链接
筛选器	7	筛选器 CRUD 和辅助元数据
搜索	6	通用搜索和特定实体搜索
邮箱	6	邮件线程和消息
阶段	5	管道阶段 CRUD（v2）
任务	5	项目任务管理
目标	5	目标 CRUD 和结果
通话记录	5	通话记录 CRUD 和音频附件
活动类型	5	活动类型管理
组织关系	5	组织之间的关系
渠道	4	消息渠道集成
Webhook	3	Webhook CRUD
权限集	3	权限集检查和分配
项目模板	2	项目模板发现
会议	2	视频通话服务商关联

安装

全局安装

npm install -g @nubiia/mcp-pipedrive

使用 npx（无需安装）

npx -y @nubiia/mcp-pipedrive

配置

前置条件

1. 从 Settings > API 获取 Pipedrive API 令牌
2. 安装 Claude Desktop

Claude Desktop 设置

macOS

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Windows

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

环境变量

变量	必需	默认值	说明
PIPEDRIVE_API_TOKEN	是	-	你的 Pipedrive API 令牌
PIPEDRIVE_READ_ONLY	否	false	启用只读模式（阻止所有写入操作）
PIPEDRIVE_TOOLSETS	否	deals,persons,organizations,activities	以逗号分隔的已启用工具类别列表
LOG_LEVEL	否	info	日志级别（debug、info、warn、error）

高级配置示例

只读模式

适用于探索性使用，或希望避免意外修改的情况：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_READ_ONLY": "true"
      }
    }
  }
}

筛选工具集

仅启用特定工具类别：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_TOOLSETS": "deals,persons,search"
      }
    }
  }
}

调试日志

启用详细日志以便排查问题：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

使用示例

示例 1：创建带联系人的交易

Claude, create a new deal for "Enterprise Software License" worth $50,000.
The contact is John Smith ([email protected]). Set the expected close date
to the end of next month and add a follow-up call for tomorrow.

Claude 将会：

1. 搜索或创建联系人“John Smith”
2. 创建与此联系人关联的交易
3. 安排明天的通话活动
4. 提供包含 ID 和后续步骤的摘要

示例 2：搜索联系人

Find all contacts at Acme Corporation and show me their recent deals.

Claude 将会：

1. 搜索名称为“Acme Corporation”的组织
2. 获取与该组织关联的所有联系人
3. 检索每位联系人的交易
4. 按类别整理结果并显示总数

示例 3：管理活动

Show me all overdue activities for my open deals and reschedule them
to next week.

Claude 将会：

1. 列出所有 done=false 且截止日期已过的活动
2. 筛选出与未关闭交易关联的活动
3. 将每项活动更新为下周的新日期
4. 提供重新安排事项的摘要

示例 4：使用自定义字段

Before creating this deal, show me what custom fields are available
for deals and explain what each one means.

Claude 将会：

1. 访问 pipedrive://custom-fields 资源
2. 提取交易专属的自定义字段
3. 显示字段名称、类型和选项
4. 说明如何在创建交易时使用这些字段

示例 5：管理销售管道

Generate a pipeline report showing deal counts and total values for
each stage in my sales pipeline.

Claude 将会：

1. 使用 pipedrive://pipelines 资源
2. 按阶段获取交易摘要
3. 计算总数和百分比
4. 整理为易读的报告

示例 6：每周审查工作流

Run the weekly pipeline review prompt.

Claude 将会：

1. 执行 weekly-pipeline-review 提示词
2. 按阶段收集所有未关闭的交易
3. 计算指标（赢单／丢单、即将成交、停滞的交易）
4. 生成可执行的建议

自定义字段

创建或更新交易、联系人、组织、产品或潜在客户时，可通过显示名称传递自定义字段值：

{
  "title": "ACME Enterprise Deal",
  "value": 50000,
  "currency": "USD",
  "custom_fields": {
    "Industria": "Tech",
    "Budget": 50000
  }
}

MCP 服务会自动将名称解析为 Pipedrive 哈希键。完整指南请参阅 docs/CUSTOM_FIELDS.md。

阶段和潜在客户标签管理

直接通过大模型管理销售管道阶段和潜在客户标签：

{ "name": "Qualified", "pipeline_id": 1, "deal_probability": 75 }

通过异步的 *_convert_to_*／*_convert_status 工具对，将符合条件的潜在客户转换为交易（或将交易退回为潜在客户）。

交易分期付款

管理交易的计划固定付款（API v2——现代版本，用于替代旧版订阅功能）：

{ "id": 123, "description": "Deposit", "amount": 500, "billing_date": "2026-01-15" }

工具：deals_list_installments、deals_add_installment、deals_update_installment、 deals_delete_installment。

完整覆盖所有字段

字段工具现已覆盖所有实体：交易、联系人、组织、产品、潜在客户和 备注的字段列表（fields_list_lead_fields、fields_list_note_fields——只读）， 以及通过 API v2 对项目字段进行完整的 CRUD 操作（fields_list_project_fields、 fields_create_project_field、fields_update_project_field、fields_delete_project_field）。

架构

核心组件

• PipedriveClient - 带限流、缓存和重试逻辑的 HTTP 客户端
• Rate Limiter - 基于 Bottleneck 的限流器（10 req/s，支持突发容量）
• Cache Layer - 基于 TTL 的缓存，使用 LRU 淘汰策略（最多 500 项）
• Retry Handler - 针对暂时性故障的指数退避机制
• Metrics Collector - 请求跟踪和性能监控
• Error Handler - 带上下文的标准化错误格式

工具结构

每个工具都遵循一致的模式：

1. Zod Schema - 输入验证，并提供描述性错误信息
2. Description - 为 LLM 提供详细的使用说明
3. Handler - 调用 PipedriveClient 的异步函数

资源

三个 MCP 资源提供只读参考数据：

• pipedrive://pipelines - 所有管道及其阶段和交易数量
• pipedrive://custom-fields - 所有实体的自定义字段定义
• pipedrive://current-user - 已认证用户的信息和权限

提示词

五种常见操作的引导式工作流：

• create-deal-workflow - 完整的交易创建流程，包括联系人和活动
• sales-qualification - BANT 资格审核清单
• follow-up-sequence - 多日活动序列
• weekly-pipeline-review - 管道健康状况报告
• lost-deal-analysis - 流失交易模式分析

性能

限流

• 默认值：每秒 10 个请求（请求间隔 100 ms）
• 突发容量：100 个令牌，每分钟补充一次
• 自动重试：429 错误会在 5 秒后自动重试

缓存策略

数据类型	TTL	原因
管道	10 min	管道结构很少发生变化
自定义字段	15 min	字段定义相对稳定
用户信息	1 min	用户数据在会话期间可能会变化
列表请求	5 min	分页结果的默认值

指标

服务会跟踪：

• 请求总数和成功率
• 平均响应时间
• 按类型统计的错误率
• 缓存命中率
• 限流事件

使用 system/metrics 工具访问指标。

API 参考

此 MCP 服务实现了 Pipedrive REST API v1。详细的 API 文档请参阅：

• Pipedrive API 参考
• Pipedrive API 更新日志
• 速率限制

高级用法

自定义字段发现

创建或更新实体之前，请检查可用的自定义字段：

// Access via MCP resource
//custom-fields

// Or use field tools
pipedrive: fields / deal - fields;
fields / person - fields;
fields / org - fields;
fields / activity - fields;

错误处理

所有工具都会返回结构化错误，包含：

• 错误类型（验证、身份验证、速率限制等）
• 详细信息
• 建议的操作
• 原始 API 错误（如适用）

工作流自动化

将多个工具串联起来，完成复杂的工作流：

1. 潜在客户资格审核

   • 搜索联系人
   • 获取其交易和活动
   • 创建资格审核备注
   • 更新交易阶段

2. 交易管道推进

   • 获取交易详情
   • 检查自定义字段要求
   • 更新自定义字段
   • 转到下一阶段
   • 创建下一项活动

3. 报告

   • 按阶段列出交易
   • 获取交易摘要
   • 计算指标
   • 格式化为 Markdown

故障排除

常见问题及解决方案请参阅 TROUBLESHOOTING.md。

快速修复：

• 身份验证错误：在 https://app.pipedrive.com/settings/api 验证你的 API 令牌
• 速率限制：降低请求频率或启用缓存
• 验证错误：检查工具输入架构和必填字段
• 在 Claude 中看不到工具：更改配置后重启 Claude Desktop

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

开发环境设置

# Clone the repository
git clone https://github.com/nubiia-dev/mcp-pipedrive.git
cd mcp-pipedrive

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run with auto-reload during development
npm run dev

运行测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run with UI
npm run test:ui

安全

请参阅 SECURITY.md 了解我们的安全政策以及如何报告漏洞。

重要：切勿将 API 令牌提交到版本控制中。请始终使用环境变量。

关于 Nubiia

此 MCP 服务由 Nubiia 构建并维护。

Nubiia 帮助企业通过 AI 实现流程自动化并集成各种工具：定制 MCP 服务、与 CRM 和 ERP 集成（Pipedrive、Holded 等），以及将业务数据与 Claude 等助手连接起来的 Agent。这个 @nubiia/mcp-pipedrive 是我们开源工作的一份示例。

👉 想为你的企业集成工具或实现 AI 自动化吗？nubiia.es · ✉️ [email protected]

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

灵感来自 mcp-holded——一个出色的 Holded CRM MCP 服务实现。

支持

• Nubiia — AI 自动化与集成：nubiia.es
• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 文档：docs/

更新日志

版本历史和发布说明请参阅 CHANGELOG.md。

路线图

• 支持 Webhook，实现实时更新
• 支持批量操作，实现批量更新
• 支持通过复杂查询进行高级筛选
• 导出/导入功能
• 与其他 CRM 集成
• 支持 GraphQL

作者

由 Nubiia 构建 — nubiia.es · [email protected]

维护者：Samuel Fraga — GitHub

---

由 Nubiia 倾心打造