AI导哈

销售队列服务

一个为Pipedrive提供的只读模型上下文协议（MCP）服务器，用于生成包含逾期跟进活动、今日跟进活动和缺少下一步行动的交易的销售摘要。

  • by alvarolloret
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 alvarolloret/pipedrive-mcp

使用说明

Miinta Pipedrive MCP v0.1

Pipedrive的只读MCP（模型上下文协议）服务器，提供摘要就绪的销售队列，具有：

  • 逾期的后续活动 （来自Pipedrive过滤器）
  • 定于今天举行后续活动 （来自Pipedrive过滤器）
  • 交易缺少下一步行动 （来自Pipedrive过滤器）

特性

  • 单一工具: miinta.sales_queue.get -返回全面的销售摘要
  • 管道驱动API v2：使用现代Pipedrive API进行活动、交易、人员、组织和阶段
  • 数据富集:
    • 交易的阶段名称
    • 个人联系信息（电子邮件）
    • 具有可配置公司域的直接交易URL
    • 活动逾期天数计算
    • 交易元数据（未完成的活动计数、上次邮件次数）
  • 智能功能:
    • 基于光标的分页支持
    • 个人/组织批量取数（避免N+1查询）
    • 缓存以提高性能（可配置TTL）
    • 可配置的时区支持（默认：欧洲/马德里）
    • 用于流通信的标准MCP标准传输
    • Pipedrive API的承载身份验证
  • 灵活的：每个请求提供的筛选器ID（环境中没有硬编码）

快速开始

  1. git clone https://github.com/alvarolloret/pipedrive-mcp.git && cd pipedrive-mcp
  2. make all
  3. 使用一个命令添加MCP（选择一个）： claude mcp add pipedrive -- docker run -i --rm --env-file /Users/alvarodemuller/miinta/pipedrive-mcp/.env pipedrive-mcp 或 codex mcp add pipedrive -- docker run -i --rm --env-file /Users/alvarodemuller/miinta/pipedrive-mcp/.env pipedrive-mcp

配置

Pipedrive API令牌

从Pipedrive获取您的API令牌：

  1. 转到您的Pipedrive帐户设置
  2. 导航到“个人首选项”→ API
  3. 复制您的API令牌

创建一个 .env 文件基于 .env.example:

# Required: Pipedrive API Token (Bearer token)
PIPEDRIVE_API_TOKEN=your_pipedrive_api_token_here

# Optional: Pipedrive API Base URL (default: https://api.pipedrive.com/v2)
PIPEDRIVE_API_BASE=https://api.pipedrive.com/v2

# Optional: Pipedrive Company Domain for deal URLs (default: app.pipedrive.com)
# Example: yourcompany.pipedrive.com
PIPEDRIVE_COMPANY_DOMAIN=yourcompany.pipedrive.com

# Optional: MCP Authentication Token (required if not localhost)
MCP_AUTH_TOKEN=your_mcp_auth_token_here

# Optional: Default timezone (default: Europe/Madrid)
DEFAULT_TIMEZONE=Europe/Madrid

# Optional: Cache TTL in seconds (default: 3600)
CACHE_TTL_SECONDS=3600

# Optional: Maximum items per section (default: 50)
MAX_ITEMS_PER_SECTION=50

# Optional: Transport mode - stdio, http, or sse (default: stdio)
TRANSPORT_MODE=stdio

# Optional: HTTP Server Port (default: 3000, only used if TRANSPORT_MODE is http or sse)
HTTP_PORT=3000

所需的管道驱动过滤器

您需要在Pipedrive帐户中创建三个已保存的过滤器：

  1. 逾期活动筛选器：筛选具有以下条件的活动 done=false 和 due_date < today
  2. 今日活动筛选器：筛选具有以下条件的活动 done=false 和 due_date = today
  3. 交易缺少下一步行动筛选器：筛选未安排下一个活动的未结交易

从Pipedrive UI或API获取筛选器ID。这些将在调用工具时提供（不在环境变量中）。

MCP工具

服务器公开了一个工具： miinta.sales_queue.get

输入模式（JSON模式）：

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "filters": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "overdue_activities_filter_id": { "type": "integer" },
        "today_activities_filter_id": { "type": "integer" },
        "missing_next_action_deals_filter_id": { "type": "integer" }
      },
      "required": [
        "overdue_activities_filter_id",
        "today_activities_filter_id",
        "missing_next_action_deals_filter_id"
      ]
    },
    "limits": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "overdue": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 },
        "today": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 },
        "missing": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 }
      }
    },
    "timezone": { "type": "string", "default": "Europe/Madrid" },
    "now": {
      "type": "string",
      "description": "Optional ISO datetime override for deterministic testing"
    },
    "include_people_orgs": { "type": "boolean", "default": true }
  },
  "required": ["filters"]
}

请求示例：

{
  "filters": {
    "overdue_activities_filter_id": 111,
    "today_activities_filter_id": 222,
    "missing_next_action_deals_filter_id": 333
  },
  "limits": {
    "overdue": 25,
    "today": 25,
    "missing": 25
  },
  "timezone": "Europe/Madrid",
  "include_people_orgs": true
}

示例响应：

{
  "generated_at": "2026-02-16T07:45:00+01:00",
  "timezone": "Europe/Madrid",
  "sections": {
    "overdue": [
      {
        "activity_id": 123,
        "activity_subject": "Follow-up email",
        "activity_type": "email",
        "due_date": "2026-02-14",
        "days_overdue": 2,
        "deal": {
          "deal_id": 456,
          "title": "Escola X — Pilot",
          "stage_id": 3,
          "stage_name": "Conversation open neutral",
          "url": "https://yourcompany.pipedrive.com/deal/456"
        },
        "person": {
          "id": 10,
          "name": "Maria Rius",
          "email": "maria@example.com"
        },
        "org": {
          "id": 20,
          "name": "Escola X"
        }
      }
    ],
    "due_today": [],
    "missing_next_action": [
      {
        "deal_id": 789,
        "title": "Universitat Y — Training",
        "stage_id": 2,
        "stage_name": "Contact",
        "owner_id": 1,
        "undone_activities_count": 0,
        "next_activity_id": null,
        "last_outgoing_mail_time": "2026-02-10T09:12:00Z",
        "last_incoming_mail_time": null,
        "url": "https://yourcompany.pipedrive.com/deal/789",
        "person": {
          "id": 11,
          "name": "Joan Garcia"
        },
        "org": {
          "id": 21,
          "name": "Universitat Y"
        }
      }
    ]
  },
  "stats": {
    "overdue_count": 1,
    "due_today_count": 0,
    "missing_next_action_count": 1
  },
  "source": {
    "filter_ids": {
      "overdue_activities_filter_id": 111,
      "today_activities_filter_id": 222,
      "missing_next_action_deals_filter_id": 333
    }
  }
}

建筑

  • Pipedrive客户端 (pipedrive-client.ts)：处理所有Pipedrive API v2交互
    • 活动过滤 done=false，排序
    • 交易筛选 status=open, include_fields
    • 基于光标的分页
    • 个人/组织批量取件
  • 缓存 (cache.ts)：支持TTL的内存缓存
  • 销售排队服务 (sales-queue.ts)：用于聚合和丰富数据的业务逻辑
    • 阶段名称解析
    • 逾期天数计算
    • 通过批量提取来丰富个人/组织
    • 处理公司域的URL生成
  • MCP服务器 (index.ts)：使用stdio传输实现MCP协议

API版本

此服务器使用Pipedrive API v2终结点：

  • /v2/activities -与 filter_id, done=false, sort_by=due_date
  • /v2/deals -与 filter_id, status=open, include_fields
  • /v2/persons -散装 ids 参数
  • /v2/organizations -散装 ids 参数
  • /v2/stages -缓存用于阶段名称解析

错误处理

服务器根据MCP规范实现了两层错误处理：

  1. 协议错误 （JSON-RPC）用于无效参数/未知工具
  2. 工具执行错误：返回 isError: true 带有可读的错误消息，用于：
    • Pipedrive身份验证失败
    • 速率限制/瞬态上游误差
    • 筛选器id无效/权限问题
    • 缺少必要参数

发展

# Build TypeScript only
make build

# Full rebuild (clean + Docker image)
make all

# Clean compiled output
make clean

验收标准

服务器在以下情况下被视为“生产就绪”：

  • ✅ 通过工具调用参数接受三个过滤器ID
  • ✅ 从每个筛选器返回正确的项目
  • ✅ 计算正确 days_overdue 在指定时区
  • ✅ 解决正确 stage_name 缓存阶段图中的值
  • ✅ 包括可用的个人/组织名称
  • ✅ 使用生成有效交易链接 PIPEDRIVE_COMPANY_DOMAIN
  • ✅ 通过以下方式处理分页 cursor 直到达到要求的限额
  • ✅ 包括交易字段： undone_activities_count, last_incoming_mail_time, last_outgoing_mail_time
  • ✅ 对个人/组织使用批量提取，以避免N+1查询
  • ✅ 以精确的规范格式返回输出 sections, stats, source

许可证

国际学生委员会

相关 MCP