Pipedrive MCP Server

Pipedrive MCP服务器

](https://www.npmjs.com/package/@iamsamuelfraga/mcp-pipedrive)  ](https://nodejs.org)

Claude最完整、最强大的Pipedrive MCP实现

生产准备就绪 模型上下文协议 为Claude提供全面访问Pipedrive CRM API的服务器。该服务器通过自然语言对话实现了销售工作流程、交易管理、联系人组织和活动跟踪的无缝自动化。

特性

• 10个类别的100多种工具 -全面覆盖Pipedrive的核心功能
• 高级速率限制 -每秒10个请求，突发容量高达100个请求
• 多级缓存 -5-15分钟TTL用于频繁访问的数据
• 重试逻辑 -失败请求的指数回退（429500502503504）
• 全面的错误处理 -带有可操作建议的详细错误消息
• 完全支持TypeScript -贯穿始终的类型安全模式和接口
• Zod验证 -对所有输入进行运行时验证，并显示有用的错误消息
• MCP资源 -对管道、自定义字段和用户信息的只读访问
• MCP提示 -5个常见操作的指导工作流程
• 性能指标 -内置请求持续时间和成功率跟踪功能
• 只读模式 -阻止所有写入操作的可选安全模式
• 工具集筛选 -根据需要启用/禁用特定工具类别

工具类别

安装

全球安装

npm install -g @iamsamuelfraga/mcp-pipedrive

使用npx（无需安装）

npx -y @iamsamuelfraga/mcp-pipedrive

配置

先决条件

1. 从获取您的Pipedrive API令牌 设置>API
2. 已安装Claude Desktop

Claude桌面设置

macOS

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

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

视窗

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

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

环境变量

高级配置示例

只读模式

非常适合探索性使用或当您想防止意外修改时：

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

筛选工具集

仅启用特定的工具类别：

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

调试日志记录

启用详细日志记录以进行故障排除：

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@iamsamuelfraga/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 (john@acme.com). Set the expected close date
to the end of next month and add a follow-up call for tomorrow.

克劳德将：

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

示例2：搜索联系人

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

克劳德将：

1. 搜索“Acme Corporation”的组织
2. 获取与该组织相关的所有人员
3. 检索每个人的交易
4. 展示有组织的结果和总计

示例3：管理活动

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

克劳德将：

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.

克劳德将：

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.

克劳德将：

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

示例6：每周审查工作流程

Run the weekly pipeline review prompt.

克劳德将：

1. 执行 weekly-pipeline-review 提示
2. 按阶段收集所有未结交易
3. 计算指标（赢/输、接近尾声、过期交易）
4. 生成可操作的建议

建筑

核心组件

• Pipedrive客户端 -具有速率限制、缓存和重试逻辑的HTTP客户端
• 速率限制器 -基于瓶颈的限制器（10个要求/秒，爆裂能力）
• 缓存层 -基于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秒后自动重试

缓存策略

指标

服务器跟踪：

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

通过以下方式访问指标 system/metrics 工具。

API 参考

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

• Pipedrive API参考
• 管道驱动API变更日志
• 速率限制

高级用法

自定义字段发现

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

// Access via MCP resource
pipedrive://custom-fields

// Or use field tools
fields/deal-fields
fields/person-fields
fields/org-fields
fields/activity-fields

错误处理

所有工具返回结构化错误，包括：

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

工作流程自动化

将多个工具链接在一起，以实现复杂的工作流程：

1. 潜在客户资格认证

- 搜索人员 - 了解他们的交易和活动 - 创建资格说明 - 更新交易阶段

1. 交易管道移动

- 获取交易详情 - 检查自定义字段要求 - 更新自定义字段 - 进入下一阶段 - 创建下一个活动

1. 报告

- 按阶段列出交易 - 获取交易摘要 - 计算指标 - 格式为markdown

故障排除

看 故障排除.md 常见问题和解决方案。

快速修复：

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

贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

开发设置

# Clone the repository
git clone https://github.com/iamsamuelfraga/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

安全

请看 安全.md 了解我们的安全策略以及如何报告漏洞。

重要：永远不要将API令牌提交到版本控制。始终使用环境变量。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

鸣谢

灵感来自 mcp保持 -Holded CRM的优秀MCP服务器实现。

支持

• 问题:
• 讨论:
• 文档: docs/

更新日志

看 更改日志.md 查看版本历史和发行说明。

路线图

• \[\]Webhook支持实时更新
• \[\]批量更新的批量操作
• \[\]复杂查询的高级过滤
• \[\]导出/导入功能
• \[\]与其他CRM集成
• \[\]GraphQL支持

______________________________________________________________________

由 塞缪尔·弗拉加