Pipedrive MCP Server

Pipedrive MCP 服务

一个面向 Pipedrive 的单租户、可自托管的模型上下文协议服务。2.x 版本使用 Pipedrive API v2 处理交易、联系人、组织、管道、阶段、线索和项目搜索。由于 Pipedrive 尚未将笔记和用户相关 API 迁移到 v2，这些功能仍通过作用域明确的 v1 适配器隔离处理。

该服务默认只读。可以显式启用两个作用范围严格受限的写入工具，并且这两个工具始终优先预览。

要求

• Node.js 22 或 24（推荐 Node 24）
• Pipedrive API 令牌

不使用 PIPEDRIVE_DOMAIN。官方 Pipedrive 客户端会提供 API 基础 URL。

使用 stdio 安装并运行

全局安装：

npm install --global pipedrive-mcp-server
PIPEDRIVE_API_TOKEN=your-token pipedrive-mcp-server

或构建此仓库：

npm ci
npm run check
PIPEDRIVE_API_TOKEN=your-token npm start

桌面 MCP 配置示例：

{
  "mcpServers": {
    "pipedrive": {
      "command": "pipedrive-mcp-server",
      "env": {
        "PIPEDRIVE_API_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP

现代 HTTP 端点默认使用 http://127.0.0.1:3000/mcp：

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
pipedrive-mcp-server

GET /health 无需身份验证，会验证主机，并且只返回服务状态。服务会为每个会话创建独立的 MCP 服务和传输层，并在关闭时关闭所有活动会话。

绑定到非回环地址需要同时提供至少 32 个字符的 HS256 JWT 密钥和明确的主机名允许列表：

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=mcp.example.com \
MCP_ALLOWED_ORIGINS=https://app.example.com \
MCP_JWT_SECRET='replace-with-at-least-32-random-characters' \
pipedrive-mcp-server

内置 HTTP 服务不会终止 TLS。切勿将其直接暴露在不受信任的网络上：应将其置于可信的 HTTPS 反向代理之后，保持应用端口为私有，并配置代理替换（而非追加）转发标头。JWT Bearer 令牌若被捕获，便可被重放。因此，Docker Compose 默认仅将服务发布到主机回环地址；远程操作人员必须先添加 TLS 终止层，才能更改此绑定。

客户端发送 Authorization: Bearer <token>。令牌必须使用 HS256。MCP_JWT_ISSUER 和 MCP_JWT_AUDIENCE 可用于添加可选的声明验证。没有启动令牌设置。

MCP_ALLOWED_ORIGINS 是精确匹配、以逗号分隔的允许列表。该列表为空时，服务不会发送 CORS 标头；不支持通配符 CORS。MCP_ALLOWED_HOSTS 仅包含主机名，不含协议、路径或端口。

旧版 SSE

已弃用的兼容路由为 GET /sse 和 POST /messages。它们在 2.x 中默认启用，可通过 MCP_ENABLE_LEGACY_SSE=false 禁用。MCP_TRANSPORT=sse 仍是 HTTP 模式的别名，并会发出警告。计划在 3.0 中移除这些路由。

Docker

将 .env.example 复制为 .env，设置 PIPEDRIVE_API_TOKEN，并设置一个至少 32 个字符的随机 MCP_JWT_SECRET。然后运行：

docker compose up --build -d
docker compose ps

Compose 在端口 3000 上提供 /mcp，要求 MCP 路由进行 JWT 身份验证，以非特权 node 用户身份运行，并使用 Node 内置的 fetch 检查 /health。已发布的镜像使用 ghcr.io/willdent/pipedrive-mcp-server。

要在 Docker 中使用 stdio，请覆盖传输方式并禁用 HTTP 健康检查：

docker run --rm -i --no-healthcheck \
  -e PIPEDRIVE_API_TOKEN=your-token \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/willdent/pipedrive-mcp-server:latest

工具与响应约定

读取工具：

• get-users
• get-deals、get-deal、get-deal-notes、search-deals
• get-persons、get-person、search-persons
• get-organizations、get-organization、search-organizations
• get-pipelines、get-pipeline、get-stages
• search-leads、search-all

列表/搜索工具返回 JSON 文本和结构化内容，格式如下：

{
  "items": [],
  "count": 0,
  "nextCursor": "optional-cursor",
  "truncated": false,
  "filters": {}
}

单条记录工具返回 { "item": {} }。稳定的失败会返回 { "code", "message", "retryable" }，并将 MCP isError 设为 true；不会暴露原始 API 错误、凭据或包含令牌的 URL。

get-deals 不会暗中设置状态或活动日期默认值。它支持按所有者、阶段、管道、状态、更新时间、金额、游标、数量限制和通用自定义字段进行筛选。每页默认 100 条，最多 500 条。金额筛选最多扫描 2,000 笔交易；若仍有记录，会报告 truncated 和 nextCursor。按标题搜索请使用 search-deals。

受控写入

除非在 PIPEDRIVE_WRITE_TOOLS 中指定，否则不会注册任何写入工具：

PIPEDRIVE_WRITE_TOOLS=move-deal,add-deal-note

• move-deal 需要 dealId、targetStageId 和 expectedCurrentStageId。它会在更新前立即尽力检查状态是否过期。Pipedrive 不支持原子条件阶段更新，因此其他客户端的并发更改仍可能与此检查发生竞态。
• add-deal-note 最多接受 10,000 个字符的纯文本，并会在发送前对其进行 HTML 转义。
• 默认情况下，这两个工具都会先预览。只有设置 execute: true 才会执行变更。
• 审计输出仅包含操作、实体 ID、结果和时间戳，不会包含备注内容或凭据。

配置

变量	默认值	用途
PIPEDRIVE_API_TOKEN	必填	Pipedrive API 令牌
MCP_TRANSPORT	stdio	stdio、http 或已弃用的 sse 别名
MCP_HOST	127.0.0.1	HTTP 绑定地址
MCP_PORT	3000	HTTP 端口
MCP_HTTP_PATH	/mcp	Streamable HTTP 路径
MCP_ALLOWED_HOSTS	本地主机	精确的主机名允许列表
MCP_ALLOWED_ORIGINS	空	精确的 CORS 来源允许列表
MCP_ENABLE_LEGACY_SSE	true	保留 /sse 和 /messages
MCP_MAX_SESSIONS	100	HTTP/SSE 会话总数上限
MCP_SESSION_IDLE_TIMEOUT_MS	1800000	关闭空闲时间超过此时长的会话
MCP_JWT_SECRET	空	HS256 密钥；非回环地址下必填
MCP_JWT_ISSUER	空	可选的 JWT 签发者
MCP_JWT_AUDIENCE	空	可选的 JWT 受众
PIPEDRIVE_WRITE_TOOLS	空	显式写入工具允许列表
PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS	250	排队调用之间的最短间隔
PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT	2	并发调用上限

启动时会验证所有端口、路径、数值限制、来源、主机、布尔值和工具名称。

从 1.x 迁移

1. 将 Node 升级到 22 或 24。
2. 移除 PIPEDRIVE_DOMAIN、MCP_JWT_TOKEN、MCP_JWT_ALGORITHM 和 MCP_ENDPOINT。
3. 将 HTTP MCP_TRANSPORT=sse 替换为 MCP_TRANSPORT=http；如果客户端仍使用旧版 SSE，可暂时保留该别名。
4. 将现代客户端指向 /mcp；在 2.x 中，旧版客户端可以使用 /sse。
5. 更新调用方，以适配游标分页和结构化响应契约。
6. 检查交易查询：get-deals 不再默默强制使用开放状态或 365 天的活动时间窗口。
7. 在逐项审查并通过沙盒测试之前，将 PIPEDRIVE_WRITE_TOOLS 留空。

开发与发布

npm run typecheck
npm test
npm run build
npm run validate:package

自动化、Docker 和手动 Pipedrive 沙盒发布门禁，请参阅 docs/release-checklist.md。发布由标签驱动，并使用 npm 可信发布以及 GHCR 语义化标签。

范围

2.x 版本仍采用单租户、可自托管模式。Pipedrive OAuth、MCP OAuth、持久会话、广泛的 CRUD 操作以及具有破坏性的删除工具均不在计划范围内。

许可证

MIT