内容
# Pipedrive MCP 服务器
[](https://www.npmjs.com/package/@nubiia/mcp-pipedrive)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://nubiia.es)
> Claude 最完整的 Pipedrive MCP 实现
一个生产就绪的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，为 Claude 提供与 Pipedrive CRM API 的全面访问。该服务器通过自然语言对话实现销售工作流、交易管理、联系人组织和活动跟踪的无缝自动化。
> 由 **[Nubiia](https://nubiia.es)** 构建和维护 — 企业自动化和智能集成（MCP、Holded、Pipedrive 等）。想为您的公司做类似的事情吗？请在 **[nubiia.es](https://nubiia.es)** 上联系我们。
## 功能
- **29 个类别中的 300+ 工具** - 完整的 Pipedrive REST API（v1 + v2）覆盖
- **高级速率限制** - 每秒 10 个请求，突发容量高达 100 个请求
- **多级缓存** - 频繁访问数据的 TTL 为 5-15 分钟
- **重试逻辑** - 失败请求的指数回退（429、500、502、503、504）
- **全面错误处理** - 详细的错误消息和可行的建议
- **完整的 TypeScript 支持** - 整个过程中类型安全的模式和接口
- **Zod 验证** - 所有输入的运行时验证，带有帮助性的错误消息
- **MCP 资源** - 管道、自定义字段和用户信息（只读）
- **MCP 提示** - 5 个用于常见操作的引导工作流
- **性能指标** - 内置的请求持续时间和成功率跟踪
- **只读模式** - 可选的安全模式，阻止所有写操作
- **工具集过滤** - 根据需要启用/禁用特定的工具类别
## 工具类别
29 个类别中的 307 个工具 — 完整的 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 | 视频通话提供者链接 |
## 安装
### 全局安装
```bash
npm install -g @nubiia/mcp-pipedrive
```
### 使用 npx（无需安装）
```bash
npx -y @nubiia/mcp-pipedrive
```
## 配置
### 先决条件
1. 从 [设置 > API](https://app.pipedrive.com/settings/api) 获取您的 Pipedrive API 令牌
2. 安装 Claude Desktop
### Claude Desktop 设置
#### macOS
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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`:
```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`） |
### 高级配置示例
#### 只读模式
适用于探索性使用或希望防止意外修改：
```json
{
"mcpServers": {
"pipedrive": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-pipedrive"],
"env": {
"PIPEDRIVE_API_TOKEN": "your_token",
"PIPEDRIVE_READ_ONLY": "true"
}
}
}
}
```
#### 过滤工具集
仅启用特定工具类别：
```json
{
"mcpServers": {
"pipedrive": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-pipedrive"],
"env": {
"PIPEDRIVE_API_TOKEN": "your_token",
"PIPEDRIVE_TOOLSETS": "deals,persons,search"
}
}
}
}
```
#### 调试日志记录
启用详细日志记录以进行故障排除：
```json
{
"mcpServers": {
"pipedrive": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-pipedrive"],
"env": {
"PIPEDRIVE_API_TOKEN": "your_token",
"LOG_LEVEL": "debug"
}
}
}
}
```
## 使用示例
### 示例 1：创建交易与联系人
```
Claude, 为“Enterprise Software License”创建一个新的交易，价值 50,000 美元。
联系人是 John Smith (john@acme.com)。设置预期关闭日期
到下个月的最后一天，并添加明天的后续通话。
```
Claude 将：
1. 搜索或创建人员“John Smith”
2. 创建与此人员关联的交易
3. 为明天安排活动电话
4. 提供具有 ID 和下一步的摘要
### 示例 2：搜索联系人
```
查找 Acme Corporation 的所有联系人并显示他们的最近交易。
```
Claude 将：
1. 搜索组织以获取“Acme Corporation”
2. 获取与该组织关联的所有人员
3. 检索每个人员的交易
4. 以总计的形式呈现有组织的结果
### 示例 3：管理活动
```
显示我的开放交易的所有逾期活动并重新安排
到下周。
```
Claude 将：
1. 列出所有活动状态为 `done=false` 且过期日期为过去的活动
2. 筛选开放交易的相关活动
3. 更新每个活动以获取下周的新日期
4. 提供已重新安排的项目摘要
### 示例 4：使用自定义字段
```
在创建此交易之前，请显示可用于交易的自定义字段
并解释每个字段的含义。
```
Claude 将：
1. 访问 `pipedrive://custom-fields` 资源
2. 提取交易特定的自定义字段
3. 显示字段名称、类型和选项
4. 解释如何在交易创建中使用它们
### 示例 5：管道管理
```
生成一个管道报告，显示每个阶段的交易数量和总价值
在我的销售管道中。
```
Claude 将：
1. 使用 `pipedrive://pipelines` 资源
2. 获取按阶段分组的交易摘要
3. 计算总值和百分比
4. 格式化为可读的报告
### 示例 6：每周审查工作流
```
运行每周管道审查提示。
```
Claude 将：
1. 执行 `weekly-pipeline-review` 提示
2. 收集所有开放交易按阶段分组
3. 计算指标（已赢/已输、接近关闭、停滞交易）
4. 生成可行的建议
## 自定义字段
在创建或更新交易、人员、组织、产品或引流线索时，通过显示名称传递自定义字段值：
```json
{
"title": "ACME Enterprise Deal",
"value": 50000,
"currency": "USD",
"custom_fields": {
"Industria": "Tech",
"Budget": 50000
}
}
```
MCP 服务器自动将名称解析为 Pipedrive 哈希键。有关完整指南，请参见 `docs/CUSTOM_FIELDS.md`。
### 阶段和引流线索标签管理
直接从 LLM 管理管道阶段和引流线索标签：
```json
{ "name": "Qualified", "pipeline_id": 1, "deal_probability": 75 }
```
通过异步 `*_convert_to_*` / `*_convert_status` 工具对进行转换（或将交易回滚为引流线索）。
### 交易分期付款
管理交易上的预定、固定付款（API v2 - 旧版订阅功能的现代替代方案）：
```json
{ "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 客户端
- **速率限制器** - 基于瓶颈的限制器（10 req/s，突发容量）
- **缓存层** - 基于 TTL 的缓存，具有 LRU 驱逐（最大 500 项）
- **重试处理程序** - 针对暂时性故障的指数回退
- **指标收集器** - 请求跟踪和性能监控
- **错误处理程序** - 标准化的错误格式化，具有上下文
### 工具结构
每个工具遵循一致的模式：
1. **Zod 模式** - 输入验证，具有描述性错误
2. **描述** - LLM 的详细使用说明
3. **处理程序** - 调用 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 毫秒之间的请求）
- **突发**：100 个令牌水库，每分钟充值
- **自动重试**：429 错误自动重试 5 秒后
### 缓存策略
| 数据类型 | TTL | 原因 |
| --- | --- | --- |
| 管道 | 10 分钟 | 管道结构很少更改 |
| 自定义字段 | 15 分钟 | 字段定义相对静态 |
| 用户信息 | 1 分钟 | 用户数据在会话期间可能更改 |
| 列表请求 | 5 分钟 | 分页结果的默认设置 |
### 指标
服务器跟踪：
- 总请求和成功率
- 平均响应时间
- 按类型划分的错误率
- 缓存命中率
- 速率限制事件
使用 `system/metrics` 工具访问指标。
## API 参考
MCP 服务器实现 Pipedrive REST API v1. 有关详细 API 文档，请参阅：
- [Pipedrive API 参考](https://developers.pipedrive.com/docs/api/v1)
- [Pipedrive API 更改日志](https://developers.pipedrive.com/changelog)
- [速率限制](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting)
## 高级用法
### 自定义字段发现
在创建或更新实体之前，请检查可用的自定义字段：
```javascript
// 通过 MCP 资源访问
//custom-fields
// 或使用字段工具
pipedrive: fields / deal - fields;
fields / person - fields;
fields / org - fields;
fields / activity - fields;
```
### 错误处理
所有工具返回结构化错误：
- 错误类型（验证、身份验证、速率限制等）
- 详细消息
- 建议的操作
- 原始 API 错误（如果适用）
### 工作流自动化
将多个工具链接在一起以实现复杂的工作流：
1. **潜在客户资格**
- 搜索人员
- 获取他们的交易和活动
- 创建资格笔记
- 更新交易阶段
2. **交易管道移动**
- 获取交易详情
- 检查自定义字段要求
- 更新自定义字段
- 移动到下一阶段
- 创建下一个活动
3. **报告**
- 列出按阶段的交易
- 获取交易摘要
- 计算指标
- 格式化为 Markdown
4. **导出/导入功能**
- 列表交易阶段
- 获取交易摘要
- 计算指标
- 格式化为 Markdown
## 故障排除
请参阅 [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) 常见问题和解决方案。
快速修复：
- **身份验证错误**：在 https://app.pipedrive.com/settings/api 验证您的 API 令牌
- **速率限制**：减少请求频率或启用缓存
- **验证错误**：检查工具输入模式和必填字段
- **看不到 Claude 中的工具**：在配置更改后重启 Claude Desktop
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 指南。
### 开发设置
```bash
# 克隆存储库
git clone https://github.com/nubiia-dev/mcp-pipedrive.git
cd mcp-pipedrive
# 安装依赖
npm install
# 构建项目
npm run build
# 运行测试
npm test
# 运行并在开发过程中自动重新加载
npm run dev
```
### 运行测试
```bash
# 运行所有测试
npm test
# 运行覆盖率
npm run test:coverage
# 运行 UI
npm run test:ui
```
## 安全
请参阅 [SECURITY.md](./SECURITY.md) 了解我们的安全政策以及如何报告漏洞。
**重要**：永远不要将您的 API 令牌提交到版本控制中。始终使用环境变量。
## 关于 Nubiia
本 MCP 服务器由 **[Nubiia](https://nubiia.es)** 构建和维护。
[Nubiia](https://nubiia.es) 帮助企业 **自动化流程并将工具与 AI 集成**：定制 MCP 服务器、CRM 和 ERP 集成（Pipedrive、Holded 等），以及连接您业务数据的代理，如 Claude。`@nubiia/mcp-pipedrive` 是我们公开提供的示例。
👉 您想为您的业务提供 AI 集成或自动化吗？ **[nubiia.es](https://nubiia.es)** · ✉️ [hola@nubiia.es](mailto:hola@nubiia.es)
## 许可证
该项目根据 MIT 许可证授权 - 请参阅 [LICENSE](./LICENSE) 文件了解详情。
## 致谢
灵感来自 [mcp-holded](https://github.com/ivo-toby/mcp-holded) - 一个优秀的 Holded CRM 的 MCP 服务器实现。
## 支持
- **Nubiia — AI 自动化和集成**：[nubiia.es](https://nubiia.es)
- **问题**：[GitHub Issues](https://github.com/nubiia-dev/mcp-pipedrive/issues)
- **讨论**：[GitHub Discussions](https://github.com/nubiia-dev/mcp-pipedrive/discussions)
- **文档**：[docs/](./docs/)
## 更新日志
请参阅 [CHANGELOG.md](./CHANGELOG.md) 获取版本历史和发布说明。
## 路线图
- [ ] 实时更新的 Webhook 支持
- [ ] 批量操作以进行批量更新
- [ ] 具有复杂查询的高级过滤
- [ ] 导出/导入功能
- [ ] 与其他 CRM 集成
- [ ] GraphQL 支持
## 作者
由 **[Nubiia](https://nubiia.es)** 构建 - [nubiia.es](https://nubiia.es) · [hola@nubiia.es](mailto:hola@nubiia.es)
维护者：Samuel Fraga - [GitHub](https://github.com/iamsamuelfraga)
---
由 [Nubiia](https://nubiia.es) 倾心打造
Made with dedication by [Nubiia](https://nubiia.es)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器