Pipedrive MCP Server

这是一个用于与Pipedrive CRM API交互的Model Control Protocol (MCP)服务器实现。此服务器使Claude能够通过MCP工具调用来创建、读取、更新和删除Pipedrive记录。

功能

此MCP服务器实现了以下Pipedrive功能：

• 人员 - 创建、读取、更新、删除和搜索人员实体
• 组织 - 管理组织及其关注者
• 交易 - 创建、管理和搜索交易，包括交易产品
• 潜在客户 - 创建、管理和搜索潜在客户，包括潜在客户标签
• 活动 - 跟踪和管理活动及活动类型
• 项目搜索 - 在Pipedrive实体中进行全局和字段特定搜索

附加功能：

• 带有全面错误处理的异步API客户端
• 特性标志以启用/禁用特定模块
• 为可维护性设计的垂直切片架构
• 全面的测试覆盖率

快速开始使用Claude代码

这是使用Pipedrive MCP服务器并在您的Claude桌面应用程序中设置它的最快方法：

1. 安装所需工具

打开您的终端或命令提示符并运行以下命令：

# 安装Python的uv包管理器（如果尚未安装）
curl -sSf https://install.python-uv.org/uv | python3 -

有关uv的详细安装说明，请访问：Astral的UV安装文档

2. 下载代码

无需GitHub账户！ 只需在终端中运行以下命令：

选择一个您希望下载代码的文件夹，并运行这些命令：

# 克隆仓库（下载代码）
git clone https://github.com/Wirasm/pipedrive-mcp.git

# 进入项目文件夹
cd pipedrive-mcp

3. 安装Python依赖项

在您的终端中准确地运行以下命令：

# 安装所有必需的包
uv sync

4. 设置您的Pipedrive凭证

1. 在项目文件夹中找到.env.example文件
2. 复制并将其重命名为.env
3. 使用任何文本编辑器打开.env文件
4. 将占位符替换为您实际的Pipedrive信息：

PIPEDRIVE_API_TOKEN=your_api_token
PIPEDRIVE_COMPANY_DOMAIN=your_company_domain

在.env文件中看到的所有其他配置都是可选的，可以保持原样。

获取您的Pipedrive API令牌：

1. 登录到您的Pipedrive帐户
2. 单击右上角的个人资料图片
3. 选择“个人偏好设置”
4. 转到“API”选项卡
5. 如果您还没有令牌，则点击“生成新令牌”
6. 复制生成的令牌并粘贴到.env文件中

对于公司域名： 如果您Pipedrive的URL是https://mycompany.pipedrive.com/pipeline，则您的域名是mycompany

5. 在Claude Desktop中安装MCP服务器

在您的终端中运行以下命令：

# 安装MCP服务器
mcp install server.py

这将自动注册Pipedrive工具到Claude Desktop。

6. 开始使用Pipedrive与Claude

1. 重要： 如果Claude Desktop应用程序已经在运行，请重新启动它
2. 打开Claude Desktop
3. 启动新的聊天，Claude现在可以与您的Pipedrive CRM互动！

尝试让Claude显示“我的最近交易”或“在这里创建一个新的联系人，以下是详细信息：...”来开始使用。

可用的MCP工具

人员工具

工具名称	描述
create_person_in_pipedrive	在Pipedrive CRM中创建一个新人员
get_person_from_pipedrive	根据ID检索特定人员的详细信息
update_person_in_pipedrive	更新Pipedrive中的现有人员
delete_person_from_pipedrive	从Pipedrive中删除人员
search_persons_in_pipedrive	按姓名、电子邮件、电话等搜索人员

组织工具

工具名称	描述
create_organization_in_pipedrive	在Pipedrive中创建一个新组织
get_organization_from_pipedrive	根据ID检索组织详细信息
update_organization_in_pipedrive	更新现有的组织
delete_organization_from_pipedrive	删除组织
list_organizations_in_pipedrive	列出组织，带有过滤和分页
search_organizations_in_pipedrive	按名称或其他标准搜索组织
add_follower_to_organization	将用户添加为组织的关注者
delete_follower_from_organization	从组织中移除关注者

交易工具

工具名称	描述
create_deal_in_pipedrive	创建一个新交易
get_deal_from_pipedrive	根据ID检索交易详细信息
update_deal_in_pipedrive	更新现有的交易
delete_deal_from_pipedrive	删除交易
list_deals_in_pipedrive	列出交易，带有过滤和分页
search_deals_in_pipedrive	按标题或其他标准搜索交易
add_product_to_deal	将产品添加到交易中
update_deal_product	更新与交易关联的产品
delete_product_from_deal	从交易中移除产品

潜在客户工具

工具名称	描述
create_lead_in_pipedrive	创建一个新潜在客户
get_lead_from_pipedrive	根据ID检索潜在客户的详细信息
update_lead_in_pipedrive	更新现有的潜在客户
delete_lead_from_pipedrive	删除潜在客户
list_leads_in_pipedrive	列出潜在客户，带有过滤和分页
search_leads_in_pipedrive	按标题或其他标准搜索潜在客户
get_lead_labels	检索可用的潜在客户标签
get_lead_sources	检索可用的潜在客户来源

项目搜索工具

工具名称	描述
search_items_in_pipedrive	在多个项目类型之间进行全局搜索
search_field_in_pipedrive	在给定实体类型中搜索特定字段值

特性模块

该项目遵循垂直切片架构，每个特性都有自己的目录：

• persons/ - 人员实体管理
• organizations/ - 组织实体管理
• deals/ - 交易管理，包括产品
• leads/ - 潜在客户管理，包括标签
• activities/ - 活动跟踪和管理
• item_search/ - 跨实体搜索功能
• shared/ - 跨特性使用的通用工具

开始使用

预备条件

• Python 3.12+
• uv - 快速的Python包管理器
• mcp CLI - Claude的模型控制协议工具
• Docker（可选）- 用于容器化部署

安全注意事项

此MCP服务器实施了几项安全措施：

• 当本地运行时，默认绑定到localhost（127.0.0.1）
• 正确的错误处理和日志记录

部署时：

• 对于本地开发，保持默认主机（127.0.0.1）
• 对于容器部署，设置CONTAINER_MODE=true

克隆仓库

git clone git@github.com:Wirasm/pipedrive-mcp.git
cd pipedrive-mcp

设置环境

1. 创建虚拟环境并安装依赖项：

uv venv
source .venv/bin/activate  # 在Unix/macOS上
# 或
.venv\Scripts\activate     # 在Windows上
uv pip install -e .

2. 在根目录下创建一个.env文件：

# API凭证
PIPEDRIVE_API_TOKEN=your_api_token
PIPEDRIVE_COMPANY_DOMAIN=your_company_domain  # 只填写子域部分（例如，从mycompany.pipedrive.com中提取的"mycompany"）

# 服务器配置
HOST=127.0.0.1  # 本地开发使用127.0.0.1，仅在容器中使用0.0.0.0
PORT=8152
TRANSPORT=sse   # "sse"或"stdio"

# 安全设置
CONTAINER_MODE=false
VERIFY_SSL=true  # 如果遇到SSL证书问题（仅限开发），设置为"false"

# 特性标志（可选）
PIPEDRIVE_FEATURE_PERSONS=true
PIPEDRIVE_FEATURE_DEALS=true
PIPEDRIVE_FEATURE_ORGANIZATIONS=true
PIPEDRIVE_FEATURE_LEADS=true
PIPEDRIVE_FEATURE_ITEM_SEARCH=true
PIPEDRIVE_FEATURE_ACTIVITIES=true

运行测试

uv run pytest

安装到Claude Desktop

mcp install server.py

本地运行

uv run server.py

使用Docker

1. 构建Docker镜像：

docker build -t pipedrive-mcp .

2. 使用环境变量运行容器：

# 重要：用您的真实Pipedrive凭证替换引号内的值
docker run -d -p 8152:8152 \
  -e PIPEDRIVE_API_TOKEN="your-actual-pipedrive-api-token" \
  -e PIPEDRIVE_COMPANY_DOMAIN="your-company-subdomain" \
  -e PORT=8152 \
  -e TRANSPORT=sse \
  -e CONTAINER_MODE=true \
  -e VERIFY_SSL=true \
  --name pipedrive-mcp-server \
  pipedrive-mcp

例如，如果您的Pipedrive域是mycompany.pipedrive.com，您应该使用：

-e PIPEDRIVE_COMPANY_DOMAIN="mycompany"

3. 检查容器是否正在运行并查看日志：

# 检查容器状态
docker ps | grep pipedrive-mcp-server

# 查看日志
docker logs pipedrive-mcp-server

4. 完成后停止并删除容器：

docker stop pipedrive-mcp-server
docker rm pipedrive-mcp-server

5. 配置Claude以使用MCP服务器：

要在此服务器上使用Claude Desktop，请在Claude桌面设置中注册MCP服务器：

• 服务器名称：Pipedrive MCP
• 端点URL：http://localhost:8152
• 认证：无

项目结构

该项目遵循垂直切片架构，代码按特性而非技术层组织：

pipedrive/
├── api/
│   ├── base_client.py                   # 核心HTTP客户端
│   ├── pipedrive_api_error.py           # API错误处理
│   ├── pipedrive_client.py              # 主客户端外观
│   ├── pipedrive_context.py             # 客户端生命周期管理
│   ├── features/
│   │   ├── tool_registry.py             # 特性注册系统
│   │   ├── tool_decorator.py            # 特性感知工具装饰器
│   │   ├── persons/                     # 人员特性模块
│   │   │   ├── client/                  # 人员API客户端
│   │   │   ├── models/                  # 人员领域模型
│   │   │   └── tools/                   # 人员MCP工具
│   │   ├── organizations/               # 组织特性模块
│   │   ├── deals/                       # 交易特性模块
│   │   ├── leads/                       # 潜在客户特性模块
│   │   ├── activities/                  # 活动特性模块
│   │   ├── item_search/                 # 搜索特性模块
│   │   └── shared/                      # 共享工具
├── feature_config.py                    # 特性配置管理
└── mcp_instance.py                      # MCP服务器配置

开发

有关详细的开发信息，请参阅CLAUDE.md。

许可证

MIT