mcp_pipedrive

Teapot-Agency/mcp_pipedrive

3.3

If you are the rightful owner of mcp_pipedrive and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that provides full CRUD access to Pipedrive CRM API v1, enabling seamless data interaction for LLM applications.

Tools
5
Resources
0
Prompts
0

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.

License: MIT Version

🚀 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

  1. Clone this repository
  2. Install dependencies: 
    npm install
  3. Create a .env file in the root directory with your configuration: 
    PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com
  4. Build the project: 
    npm run build
  5. Start the server: 
    npm start

Docker Setup

Option 1: Using Docker Compose (standalone)
  1. 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
  2. Build and run with Docker Compose: 
    docker-compose up -d
  3. 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:

  1. 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"
      }
    }
  }
}
  1. Restart Claude for Desktop
  2. 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

  1. Best: Use find-person with fuzzy matching

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

  2. Good: Use get-persons with filters

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

  3. Fallback: Use search-persons (Pipedrive's API)

    search-persons({ term: "Piotr" })
Finding an Organization

  1. Recommended: Use get-organizations with filter

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

  2. 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

License

MIT