Pipe-MCP

Pipedrive MCP Server

A Model Control Protocol (MCP) server implementation for interacting with the Pipedrive CRM API. This server enables Claude to create, read, update, and delete Pipedrive records through MCP tool calls.

Features

This MCP server implements the following Pipedrive features:

• Persons - Create, read, update, delete, and search person entities
• Organizations - Manage organizations and their followers
• Deals - Create, manage, and search deals, including deal products
• Leads - Create, manage, and search leads including lead labels
• Activities - Track and manage activities and activity types
• Item Search - Global and field-specific search across Pipedrive entities

Additional features:

• Async API client with comprehensive error handling
• Feature flags to enable/disable specific modules
• Vertical slice architecture for maintainability
• Comprehensive test coverage

Quick Start with Claude Code

The fastest way to get started with the Pipedrive MCP Server and set it up in your claude desktop app:

1. Install Required Tools

Open your terminal or command prompt and run these commands:

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

For more detailed installation instructions for uv, visit: Astral's UV Installation Documentation

2. Download the Code

No GitHub account required! Just run these commands in your terminal:

Select a folder where you want the code to be downloaded to and run these commands:

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

# Move into the project folder
cd pipedrive-mcp

3. Install Python Dependencies

Open your terminal and run this command exactly as written:

# Install all required packages
uv sync

4. Set Up Your Pipedrive Credentials

1. Find the .env.example file in the project folder
2. Make a copy and rename it to just .env
3. Open the .env file in any text editor
4. Replace the placeholders with your actual Pipedrive information:

PIPEDRIVE_API_TOKEN=your_api_token
PIPEDRIVE_COMPANY_DOMAIN=your_company_domain

All other configurations you see in the .env file are optional and can be left as is.

To get your Pipedrive API Token:

1. Log in to your Pipedrive account
2. Click on your profile picture in the top-right corner
3. Select "Personal preferences"
4. Go to the "API" tab
5. Click "Generate new token" if you don't already have one
6. Copy the generated token and paste it in the .env file

For the company domain: If your Pipedrive URL is https://mycompany.pipedrive.com/pipeline, then your domain is mycompany

5. Install the MCP Server in Claude Desktop

Open your terminal and run this command:

# Install the MCP server
mcp install server.py

This will automatically register the Pipedrive tools with Claude Desktop.

6. Start Using Pipedrive with Claude

1. Important: Restart Claude Desktop app if it was already running
2. Open Claude Desktop
3. Start a new chat, and Claude can now interact with your Pipedrive CRM!

Try asking Claude to "Show me my recent deals" or "Create a new contact here are the details: ..." to get started.

Available MCP Tools

Person Tools

Tool Name	Description
create_person_in_pipedrive	Creates a new person in Pipedrive CRM
get_person_from_pipedrive	Retrieves details of a specific person by ID
update_person_in_pipedrive	Updates an existing person in Pipedrive
delete_person_from_pipedrive	Deletes a person from Pipedrive
search_persons_in_pipedrive	Searches for persons by name, email, phone, etc.

Organization Tools

Tool Name	Description
create_organization_in_pipedrive	Creates a new organization in Pipedrive
get_organization_from_pipedrive	Retrieves organization details by ID
update_organization_in_pipedrive	Updates an existing organization
delete_organization_from_pipedrive	Deletes an organization
list_organizations_in_pipedrive	Lists organizations with filtering and pagination
search_organizations_in_pipedrive	Searches for organizations by name or other criteria
add_follower_to_organization	Adds a user as a follower of an organization
delete_follower_from_organization	Removes a follower from an organization

Deal Tools

Tool Name	Description
create_deal_in_pipedrive	Creates a new deal
get_deal_from_pipedrive	Retrieves deal details by ID
update_deal_in_pipedrive	Updates an existing deal
delete_deal_from_pipedrive	Deletes a deal
list_deals_in_pipedrive	Lists deals with filtering and pagination
search_deals_in_pipedrive	Searches for deals by title or other criteria
add_product_to_deal	Adds a product to a deal
update_deal_product	Updates a product associated with a deal
delete_product_from_deal	Removes a product from a deal

Lead Tools

Tool Name	Description
create_lead_in_pipedrive	Creates a new lead
get_lead_from_pipedrive	Retrieves lead details by ID
update_lead_in_pipedrive	Updates an existing lead
delete_lead_from_pipedrive	Deletes a lead
list_leads_in_pipedrive	Lists leads with filtering and pagination
search_leads_in_pipedrive	Searches for leads by title or other criteria
get_lead_labels	Retrieves available lead labels
get_lead_sources	Retrieves available lead sources

Item Search Tools

Tool Name	Description
search_items_in_pipedrive	Global search across multiple item types
search_field_in_pipedrive	Searches for specific field values in a given entity type

Feature Modules

The project follows a vertical slice architecture with each feature having its own directory:

• persons/ - Person entity management
• organizations/ - Organization entity management
• deals/ - Deal management including products
• leads/ - Lead management including labels
• activities/ - Activity tracking and management
• item_search/ - Cross-entity search functionality
• shared/ - Common utilities used across features

Getting Started

Prerequisites

• Python 3.12+
• uv - Fast Python package manager
• mcp CLI - Claude's Model Control Protocol tools
• Docker (optional) - For containerized deployment

Security Notes

This MCP server implements several security measures:

• Default binding to localhost (127.0.0.1) when running locally
• Proper error handling and logging

When deploying:

• For local development, keep the default host (127.0.0.1)
• For container deployment, set CONTAINER_MODE=true

Clone the Repository

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

Setup Environment

1. Create a virtual environment and install dependencies:

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

2. Create a .env file in the root directory:

# 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

Run Tests

uv run pytest

Install to Claude Desktop

mcp install server.py

Run Locally

uv run server.py

Using Docker

1. Build the Docker image:

docker build -t pipedrive-mcp .

2. Run the container with environment variables:

# 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

For example, if your Pipedrive domain is mycompany.pipedrive.com, you would use:

-e PIPEDRIVE_COMPANY_DOMAIN="mycompany"

3. Check the container is running and view logs:

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

# View logs
docker logs pipedrive-mcp-server

4. Stop and remove the container when done:

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

5. Configure Claude to use the MCP server:

To use this server with Claude Desktop, register the MCP server in Claude desktop settings:

• Server Name: Pipedrive MCP
• Endpoint URL: http://localhost:8152
• Auth: None

Project Structure

The project follows a vertical slice architecture where code is organized by features rather than by technical layers:

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

Development

For detailed development information, see CLAUDE.md.

License

MIT