Pipedrive MCP Server

A Model Context Protocol (MCP) server that provides full CRUD access to Pipedrive CRM API v1. Enable Claude and other LLM applications to read and write Pipedrive data seamlessly.

🚀 Features

Full CRUD Operations - Create, Read, Update, and Delete support for all major Pipedrive entities
40 Total Tools - 20 read operations + 20 write operations
Complete Data Access - Deals, persons, organizations, activities, notes, and leads
Custom Fields Support - Full access to custom fields and configurations
Built-in Safety - Mandatory confirmation for delete operations, soft delete with 30-day recovery
Rate Limiting - Automatic request throttling to respect API limits
Advanced Filtering - Filter deals by owner, status, date range, value, and more. Filter persons by name, email, organization, or phone
Fuzzy Search - New find-person tool with intelligent fuzzy matching and scoring
Smart Error Messages - Helpful suggestions when searches return no results
JWT Authentication - Optional JWT security for SSE transport
Docker Support - Multi-stage builds and container deployment
Dual Transport - stdio (local) and SSE (HTTP) modes

Setup

Standard Setup

Clone this repository
Install dependencies:
```
npm install
```

Create a .env file in the root directory with your configuration:

PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com

Build the project:
```
npm run build
```
Start the server:
```
npm start
```

Docker Setup

Option 1: Using Docker Compose (standalone)

Copy .env.example to .env and configure your settings:

PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com
MCP_TRANSPORT=sse  # Use SSE transport for Docker
MCP_PORT=3000

Build and run with Docker Compose:
```
docker-compose up -d
```
The server will be available at http://localhost:3000
- SSE endpoint: http://localhost:3000/sse
- Health check: http://localhost:3000/health

Option 2: Using Pre-built Docker Image

Pull and run the pre-built image from GitHub Container Registry:

For SSE transport (HTTP access):

docker run -d \
  -p 3000:3000 \
  -e PIPEDRIVE_API_TOKEN=your_api_token_here \
  -e PIPEDRIVE_DOMAIN=your-company.pipedrive.com \
  -e MCP_TRANSPORT=sse \
  -e MCP_PORT=3000 \
  ghcr.io/juhokoskela/pipedrive-mcp-server:main

For stdio transport (local use):

docker run -i \
  -e PIPEDRIVE_API_TOKEN=your_api_token_here \
  -e PIPEDRIVE_DOMAIN=your-company.pipedrive.com \
  ghcr.io/juhokoskela/pipedrive-mcp-server:main

Option 3: Integrating into Existing Project

Add the MCP server to your existing application's docker-compose.yml:

services:
  # Your existing services...

  pipedrive-mcp-server:
    image: ghcr.io/juhokoskela/pipedrive-mcp-server:main
    container_name: pipedrive-mcp-server
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PIPEDRIVE_API_TOKEN=${PIPEDRIVE_API_TOKEN}
      - PIPEDRIVE_DOMAIN=${PIPEDRIVE_DOMAIN}
      - MCP_TRANSPORT=sse
      - MCP_PORT=3000
      - PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS=${PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS:-250}
      - PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT=${PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT:-2}
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health", "||", "exit", "1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Then add the required environment variables to your .env file.

Environment Variables

Required:

PIPEDRIVE_API_TOKEN - Your Pipedrive API token
PIPEDRIVE_DOMAIN - Your Pipedrive domain (e.g., your-company.pipedrive.com)

Optional (JWT Authentication):

MCP_JWT_SECRET - JWT secret for authentication
MCP_JWT_TOKEN - JWT token for authentication
MCP_JWT_ALGORITHM - JWT algorithm (default: HS256)
MCP_JWT_AUDIENCE - JWT audience
MCP_JWT_ISSUER - JWT issuer

When JWT authentication is enabled, all SSE requests (/sse and the message endpoint) must include an Authorization: Bearer <token> header signed with the configured secret.

Optional (Rate Limiting):

PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS - Minimum time between requests in milliseconds (default: 250)
PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT - Maximum concurrent requests (default: 2)

Optional (Transport Configuration):

MCP_TRANSPORT - Transport type: stdio (default, for local use) or sse (for Docker/HTTP access)
MCP_PORT - Port for SSE transport (default: 3000, only used when MCP_TRANSPORT=sse)
MCP_ENDPOINT - Message endpoint path for SSE (default: /message, only used when MCP_TRANSPORT=sse)

Using with Claude

To use this server with Claude for Desktop:

Configure Claude for Desktop by editing your claude_desktop_config.json:

{
  "mcpServers": {
    "pipedrive": {
      "command": "node",
      "args": ["/path/to/pipedrive-mcp-server/build/index.js"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here",
        "PIPEDRIVE_DOMAIN": "your-company.pipedrive.com"
      }
    }
  }
}

Restart Claude for Desktop
In the Claude application, you should now see the Pipedrive tools available

Available Tools

Read Operations (20 tools)

Users & Search:

get-users: Get all users/owners from Pipedrive to identify owner IDs for filtering
search-all: Search across all item types (deals, persons, organizations, etc.) with improved error messages

Deals:

get-deals: Get deals with flexible filtering options (search by title, date range, owner, stage, status, value range, etc.)
get-deal: Get a specific deal by ID (including custom fields)
get-deal-notes: Get detailed notes and custom booking details for a specific deal
search-deals: Search deals by term

Persons (NEW & IMPROVED):

get-persons: 🆕 Enhanced - Get all persons with optional filtering by name, email, phone, organization ID, or organization name
find-person: ✨ NEW - Find persons using fuzzy matching across name, email, phone, and company with intelligent scoring
get-persons-by-organization: ✨ NEW - Get all persons belonging to a specific organization
get-person: Get a specific person by ID (including custom fields)
get-person-notes: Get all notes attached to a specific person
search-persons: 🆕 Enhanced - Search persons with improved error messages and suggestions
search-persons-by-notes: Search for persons who have attached notes containing a specific keyword

Organizations (NEW & IMPROVED):

get-organizations: 🆕 Enhanced - Get all organizations with optional filtering by name
get-organization: Get a specific organization by ID (including custom fields)
search-organizations: 🆕 Enhanced - Search organizations with improved error messages and suggestions

Pipelines & Stages:

get-pipelines: Get all pipelines from Pipedrive
get-pipeline: Get a specific pipeline by ID
get-stages: Get all stages from all pipelines

Leads:

search-leads: Search leads by term

Write Operations (20 tools)

Deal Operations:

create-deal: Create a new deal with custom fields support
update-deal: Update an existing deal
delete-deal: Delete a deal (soft delete with 30-day recovery, requires confirmation)

Person Operations:

create-person: Create a new contact with email and phone support
update-person: Update an existing contact
delete-person: Delete a person (soft delete with 30-day recovery, requires confirmation)

Organization Operations:

create-organization: Create a new organization with address support
update-organization: Update an existing organization
delete-organization: Delete an organization (soft delete with 30-day recovery, requires confirmation)

Activity Operations:

create-activity: Create tasks, calls, meetings, deadlines, etc.
update-activity: Update an existing activity
delete-activity: Delete an activity (soft delete with 30-day recovery, requires confirmation)

Note Operations:

create-note: Create notes attached to deals, persons, organizations, or leads
update-note: Update note content
delete-note: Delete a note (requires confirmation)

Lead Operations:

create-lead: Create a new lead
update-lead: Update an existing lead
delete-lead: Delete a lead (requires confirmation)
convert-lead-to-deal: Convert a lead to a deal with conversion tracking

Safety Guidelines

Delete Operations: All delete operations require a confirm: true parameter to prevent accidental deletions. Most deletions in Pipedrive are soft deletes with a 30-day recovery period.

Recovery: Deleted items can be recovered within 30 days via Pipedrive UI:

Navigate to: Settings > Data fields > Deleted items
Select the item type (deals, persons, organizations, activities)
Click "Restore" on the item you want to recover

Best Practices:

Always verify the entity ID before deleting
Use search/get operations first to confirm you're targeting the correct item
Document important deletions for audit purposes
Consider archiving or status changes instead of deletion when appropriate

Available Prompts

list-all-deals: List all deals in Pipedrive
list-all-persons: List all persons in Pipedrive
list-all-pipelines: List all pipelines in Pipedrive
analyze-deals: Analyze deals by stage
analyze-contacts: Analyze contacts by organization
analyze-leads: Analyze leads by status
compare-pipelines: Compare different pipelines and their stages
find-high-value-deals: Find high-value deals

🔍 Search Improvements (v2.1)

The server now includes powerful new search and filtering capabilities to address common issues with Pipedrive's search API.

Key Improvements

Problem: Pipedrive's native search API often returns empty results due to strict matching requirements.

Solution: We've added client-side filtering and fuzzy matching tools that are more reliable and flexible.

Recommended Search Strategy

Finding a Person

Best: Use find-person with fuzzy matching

find-person({ name: "Piotr", company: "Haleon" })

Good: Use get-persons with filters

get-persons({ filterName: "Piotr", organizationName: "Haleon" })

Fallback: Use search-persons (Pipedrive's API)
```
search-persons({ term: "Piotr" })
```

Finding an Organization

Recommended: Use get-organizations with filter

get-organizations({ filterName: "Haleon" })

Fallback: Use search-organizations (Pipedrive's API)
```
search-organizations({ term: "Haleon" })
```

New Tools

find-person: Fuzzy matching with scoring across multiple fields
get-persons-by-organization: Get all persons in a specific organization
Enhanced get-persons: Filter by name, email, phone, organization
Enhanced get-organizations: Filter by name

Smart Error Messages

When searches return no results, you'll now get helpful feedback:

{
  "items": [],
  "warning": "No results found using Pipedrive's search API",
  "suggestion": "Try using 'find-person' for fuzzy matching",
  "possible_reasons": [
    "Search term may be too short",
    "Pipedrive search requires exact matches",
    "Try alternative tools"
  ]
}

For detailed documentation of all improvements, see IMPROVEMENTS.md

License

MIT