AI导哈

Pipedrive CRM访问服务

一个提供对Pipedrive CRM API v1完整CRUD访问的Model Context Protocol (MCP)服务器，使Claude和其他LLM应用能够无缝读写Pipedrive数据。

  • by Teapot-Agency
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 Teapot-Agency/mcp_pipedrive

使用说明

Pipedrive MCP服务器

模型上下文协议（MCP）服务器，提供对Pipedrive CRM API v1的完全CRUD访问。使Claude和其他LLM应用程序能够无缝读写Pipedrive数据。

🚀 特性

  • 完整的CRUD操作 -为所有主要Pipedrive实体创建、读取、更新和删除支持
  • 总共40个工具 -20次读取操作+20次写入操作
  • 完成数据访问 -交易、人员、组织、活动、笔记和线索
  • 自定义字段支持 -完全访问自定义字段和配置
  • 内置安全 -强制确认删除操作，软删除，30天恢复
  • 速率限制 -遵守API限制的自动请求节流
  • 高级过滤 -按所有者、状态、日期范围、价值等筛选交易。按姓名、电子邮件、组织或电话筛选人员
  • 模糊搜索 新 find-person 智能模糊匹配评分工具
  • 智能错误消息 -搜索未返回结果时的有用建议
  • JWT身份验证 -SSE传输的可选JWT安全
  • Docker支持 -多阶段构建和容器部署
  • 双重运输 -stdio（本地）和SSE（HTTP）模式

设置

标准设置

  1. 克隆此仓库
  2. 安装依赖项：
    npm install
  3. 创建一个 .env 根目录中包含您的配置的文件：
    PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com
  4. 构建项目：
    npm run build
  5. 启动服务器：
    npm start

Docker设置

选项1：使用Docker Compose（独立）

  1. 复制 .env.example 到 .env 并配置您的设置：
    PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com
MCP_TRANSPORT=sse  # Use SSE transport for Docker
MCP_PORT=3000
  2. 使用Docker Compose构建和运行：
    docker-compose up -d
  3. 服务器将在以下时间可用 http://localhost:3000
    • SSE端点： http://localhost:3000/sse
    • 健康检查： http://localhost:3000/health

选项2：使用预构建的Docker镜像

从GitHub容器注册表中提取并运行预构建映像：

对于SSE传输（HTTP访问）：

docker run -d \
  -p 3000:3000 \
  -e PIPEDRIVE_API_TOKEN=your_api_token_here \
  -e PIPEDRIVE_DOMAIN=your-company.pipedrive.com \
  -e MCP_TRANSPORT=sse \
  -e MCP_PORT=3000 \
  ghcr.io/juhokoskela/pipedrive-mcp-server:main

对于stdio传输（本地使用）：

docker run -i \
  -e PIPEDRIVE_API_TOKEN=your_api_token_here \
  -e PIPEDRIVE_DOMAIN=your-company.pipedrive.com \
  ghcr.io/juhokoskela/pipedrive-mcp-server:main

选项3：整合到现有项目中

将MCP服务器添加到现有应用程序的 docker-compose.yml:

services:
  # Your existing services...

  pipedrive-mcp-server:
    image: ghcr.io/juhokoskela/pipedrive-mcp-server:main
    container_name: pipedrive-mcp-server
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PIPEDRIVE_API_TOKEN=${PIPEDRIVE_API_TOKEN}
      - PIPEDRIVE_DOMAIN=${PIPEDRIVE_DOMAIN}
      - MCP_TRANSPORT=sse
      - MCP_PORT=3000
      - PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS=${PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS:-250}
      - PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT=${PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT:-2}
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health", "||", "exit", "1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

然后将所需的环境变量添加到您的 .env 文件。

环境变量

必修的：

  • PIPEDRIVE_API_TOKEN -您的Pipedrive API令牌
  • PIPEDRIVE_DOMAIN -您的Pipedrive域（例如。， your-company.pipedrive.com)

可选（JWT身份验证）：

  • MCP_JWT_SECRET -用于身份验证的JWT密钥
  • MCP_JWT_TOKEN -用于身份验证的JWT令牌
  • MCP_JWT_ALGORITHM -JWT算法（默认值：HS256）
  • MCP_JWT_AUDIENCE -JWT观众
  • MCP_JWT_ISSUER -智威汤逊发行人

启用JWT身份验证时，所有SSE请求(/sse 消息端点）必须包含 Authorization: Bearer <token> 使用配置的密钥签名的标头。

可选（速率限制）：

  • PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS -请求之间的最短时间（毫秒）（默认值：250）
  • PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT -最大并发请求数（默认值：2）

可选（传输配置）：

  • MCP_TRANSPORT -运输类型： stdio （默认，供本地使用）或 sse （用于Docker/HTTP访问）
  • MCP_PORT -SSE传输端口（默认值：3000，仅在以下情况下使用 MCP_TRANSPORT=sse)
  • MCP_ENDPOINT -SSE的消息端点路径（默认值：/Message，仅在以下情况下使用 MCP_TRANSPORT=sse)

与克劳德一起使用

要将此服务器与Claude for Desktop一起使用，请执行以下操作：

  1. 通过编辑您的 claude_desktop_config.json:
{
  "mcpServers": {
    "pipedrive": {
      "command": "node",
      "args": ["/path/to/pipedrive-mcp-server/build/index.js"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here",
        "PIPEDRIVE_DOMAIN": "your-company.pipedrive.com"
      }
    }
  }
}
  1. 重新启动桌面版的Claude
  2. 在Claude应用程序中，您现在应该看到可用的Pipedrive工具

可用工具

读取操作（20个工具）

用户和搜索：

  • get-users：从Pipedrive获取所有用户/所有者，以识别所有者ID进行过滤
  • search-all：使用改进的错误消息搜索所有项目类型（交易、人员、组织等）

交易：

  • get-deals：通过灵活的筛选选项（按标题、日期范围、所有者、阶段、状态、值范围等搜索）获得交易
  • get-deal：通过ID（包括自定义字段）获取特定交易
  • get-deal-notes：获取特定交易的详细说明和定制预订详细信息
  • search-deals：按术语搜索交易

人员（新增和改进）：

  • get-persons: 🆕 增强 -通过姓名、电子邮件、电话、组织ID或组织名称进行可选筛选，获取所有人员
  • find-person: ✨ 新 -通过智能评分，在姓名、电子邮件、电话和公司之间使用模糊匹配来查找人员
  • get-persons-by-organization: ✨ 新 -获取属于特定组织的所有人员
  • get-person：通过ID（包括自定义字段）获取特定人员
  • get-person-notes：将所有笔记附加到特定的人身上
  • search-persons: 🆕 增强 -使用改进的错误消息和建议搜索人员
  • search-persons-by-notes：搜索附加了包含特定关键字的注释的人员

组织（新的和改进的）：

  • get-organizations: 🆕 增强 -获取所有可选择按名称筛选的组织
  • get-organization：按ID获取特定组织（包括自定义字段）
  • search-organizations: 🆕 增强 -使用改进的错误消息和建议搜索组织

管道和阶段：

  • get-pipelines：从Pipedrive获取所有管道
  • get-pipeline：按ID获取特定管道
  • get-stages：从所有管道中获取所有阶段

引导：

  • search-leads：按术语搜索潜在客户

写入操作（20个工具）

交易操作：

  • create-deal：使用自定义字段支持创建新交易
  • update-deal：更新现有交易
  • delete-deal：删除交易（软删除，30天恢复，需要确认）

人员操作：

  • create-person：通过电子邮件和电话支持创建新联系人
  • update-person：更新现有联系人
  • delete-person：删除一个人（软删除，30天恢复，需要确认）

组织运营：

  • create-organization：创建具有地址支持的新组织
  • update-organization：更新现有组织
  • delete-organization：删除组织（软删除，30天恢复，需要确认）

活动操作：

  • create-activity：创建任务、电话、会议、截止日期等。
  • update-activity：更新现有活动
  • delete-activity：删除活动（软删除，30天恢复，需要确认）

注释操作：

  • create-note：为交易、个人、组织或潜在客户创建附加注释
  • update-note：更新笔记内容
  • delete-note：删除注释（需要确认）

领导运营：

  • create-lead：创建新的潜在客户
  • update-lead：更新现有潜在客户
  • delete-lead：删除潜在客户（需要确认）
  • convert-lead-to-deal：通过转化跟踪将潜在客户转化为交易

安全指南

删除操作： 所有删除操作都需要 confirm: true 参数，以防止意外删除。Pipedrive中的大多数删除都是软删除，恢复期为30天。

恢复： 删除的邮件可以在30天内通过Pipedrive UI恢复：

  • 导航到：设置>数据字段>已删除邮件
  • 选择项目类型（交易、人员、组织、活动）
  • 在要恢复的项目上单击“还原”

最佳实践：

  • 删除前始终验证实体ID
  • 首先使用搜索/获取操作来确认您的目标是正确的项目
  • 记录重要删除内容以供审计
  • 在适当的时候考虑存档或更改状态，而不是删除

可用提示

  • list-all-deals：列出Pipedrive中的所有交易
  • list-all-persons：列出Pipedrive中的所有人员
  • list-all-pipelines：列出Pipedrive中的所有管道
  • analyze-deals：按阶段分析交易
  • analyze-contacts：按组织分析联系人
  • analyze-leads：按状态分析潜在客户
  • compare-pipelines：比较不同的管道及其阶段
  • find-high-value-deals：寻找高价值交易

🔍 搜索改进（v2.1）

该服务器现在包括强大的新搜索和过滤功能，以解决Pipedrive搜索API的常见问题。

关键改进

问题： Pipedrive的本机搜索API由于严格的匹配要求，经常返回空结果。

解决方案： 我们添加了更可靠、更灵活的客户端过滤和模糊匹配工具。

推荐搜索策略

寻找一个人

  1. 最佳： 使用 find-person 模糊匹配

    find-person({ name: "Piotr", company: "Haleon" })

  2. 好： 使用 get-persons 带过滤器

    get-persons({ filterName: "Piotr", organizationName: "Haleon" })

  3. 退路： 使用 search-persons （Pipedrive的API）

    search-persons({ term: "Piotr" })

寻找一个组织

  1. 推荐： 使用 get-organizations 带过滤器

    get-organizations({ filterName: "Haleon" })

  2. 退路： 使用 search-organizations （Pipedrive的API）

    search-organizations({ term: "Haleon" })

新工具

  • find-person：模糊匹配，跨多个领域评分
  • get-persons-by-organization：获取特定组织中的所有人员
  • 增强 get-persons：按姓名、电子邮件、电话、组织进行筛选
  • 增强 get-organizations：按名称筛选

智能错误消息

当搜索未返回结果时，您现在将获得有用的反馈：

{
  "items": [],
  "warning": "No results found using Pipedrive's search API",
  "suggestion": "Try using 'find-person' for fuzzy matching",
  "possible_reasons": [
    "Search term may be too short",
    "Pipedrive search requires exact matches",
    "Try alternative tools"
  ]
}

有关所有改进的详细文档，请参阅 改进.md

许可证

麻省理工学院

相关 MCP