Pipe-MCP

Pipedrive MCP 服务

用于与 Pipedrive CRM API 交互的模型控制协议（MCP）服务实现。该服务可让 Claude 通过 MCP 工具调用创建、读取、更新和删除 Pipedrive 记录。

功能

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

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

其他功能：

• 异步 API 客户端，提供全面的错误处理
• 功能标志，可启用或禁用特定模块
• 纵向切片架构，便于维护
• 全面的测试覆盖

使用 Claude Code 快速开始

以下是开始使用 Pipedrive MCP 服务并在 Claude 桌面应用中设置它的最快方法：

1. 安装所需工具

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

# Install Python's uv package manager (if not already installed)
curl -sSf https://install.python-uv.org/uv | python3 -

如需查看 uv 的详细安装说明，请访问：Astral 的 UV 安装文档

2. 下载代码

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

选择用于下载代码的文件夹，然后运行以下命令：

# Clone the repository (download the code)
git clone https://github.com/Wirasm/pipedrive-mcp.git

# Move into the project folder
cd pipedrive-mcp

3. 安装 Python 依赖项

打开终端并按原样运行此命令：

# Install all required packages
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. 选择“Personal preferences”
4. 转到“API”选项卡
5. 如果你还没有令牌，请点击“Generate new token”
6. 复制生成的令牌并粘贴到 .env 文件中

公司域名： 如果你的 Pipedrive URL 是 https://mycompany.pipedrive.com/pipeline，那么你的域名就是 mycompany

5. 在 Claude Desktop 中安装 MCP 服务

打开终端并运行此命令：

# Install the MCP server
mcp install server.py

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

6. 开始使用 Claude 操作 Pipedrive

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_in_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 的 Model Control Protocol 工具
• Docker（可选）- 用于容器化部署

安全说明

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

• 在本地运行时默认绑定到 localhost（127.0.0.1）
• 妥善处理错误并记录日志

部署时：

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

克隆代码仓库

git clone [email protected]:Wirasm/pipedrive-mcp.git
cd pipedrive-mcp

配置环境

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

uv venv
source .venv/bin/activate  # On Unix/macOS
# OR
.venv\Scripts\activate     # On Windows
uv pip install -e .

2. 在根目录中创建 .env 文件：

# API Credentials
PIPEDRIVE_API_TOKEN=your_api_token
PIPEDRIVE_COMPANY_DOMAIN=your_company_domain  # Just the subdomain portion (e.g., "mycompany" from mycompany.pipedrive.com)

# Server Configuration
HOST=127.0.0.1  # Use 127.0.0.1 for local development, 0.0.0.0 only in containers
PORT=8152
TRANSPORT=sse   # "sse" or "stdio"

# Security Settings
CONTAINER_MODE=false
VERIFY_SSL=true  # Set to "false" if you encounter SSL certificate issues (development only)

# Feature Flags (optional)
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. 使用环境变量运行容器：

# IMPORTANT: Replace values in quotes with your real Pipedrive credentials
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. 检查容器是否正在运行并查看日志：

# Check container status
docker ps | grep pipedrive-mcp-server

# View logs
docker logs pipedrive-mcp-server

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

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

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

要在 Claude Desktop 中使用此服务，请在 Claude desktop 设置中注册 MCP 服务：

• 服务名称：Pipedrive MCP
• 端点 URL：http://localhost:8152
• 身份验证：无

项目结构

该项目采用垂直切片架构，代码按功能而非技术分层组织：

pipedrive/
├── api/
│   ├── base_client.py                   # Core HTTP client
│   ├── pipedrive_api_error.py           # API error handling
│   ├── pipedrive_client.py              # Main client facade
│   ├── pipedrive_context.py             # Client lifecycle management
│   ├── features/
│   │   ├── tool_registry.py             # Feature registry system
│   │   ├── tool_decorator.py            # Feature-aware tool decorator
│   │   ├── persons/                     # Person feature module
│   │   │   ├── client/                  # Person API client
│   │   │   ├── models/                  # Person domain models
│   │   │   └── tools/                   # Person MCP tools
│   │   ├── organizations/               # Organization feature module
│   │   ├── deals/                       # Deal feature module
│   │   ├── leads/                       # Lead feature module
│   │   ├── activities/                  # Activity feature module
│   │   ├── item_search/                 # Search feature module
│   │   └── shared/                      # Shared utilities
├── feature_config.py                    # Feature configuration management
└── mcp_instance.py                      # MCP server configuration

开发

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

许可证

MIT