mcp-pipedrive

Pipedrive MCP Server

The most complete and robust Pipedrive MCP implementation for Claude

A production-ready Model Context Protocol server that provides Claude with comprehensive access to the Pipedrive CRM API. This server enables seamless automation of sales workflows, deal management, contact organization, and activity tracking through natural language conversations.

Built and maintained by Nubiia — automatización e integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así para tu empresa? Escríbenos en nubiia.es.

Features

• 300+ Tools Across 29 Categories - Complete coverage of the entire Pipedrive REST API (v1 + v2)
• Advanced Rate Limiting - 10 requests/second with burst capacity up to 100 requests
• Multi-Level Caching - 5-15 minute TTL for frequently accessed data
• Retry Logic - Exponential backoff for failed requests (429, 500, 502, 503, 504)
• Comprehensive Error Handling - Detailed error messages with actionable suggestions
• Full TypeScript Support - Type-safe schemas and interfaces throughout
• Zod Validation - Runtime validation for all inputs with helpful error messages
• MCP Resources - Read-only access to pipelines, custom fields, and user info
• MCP Prompts - 5 guided workflows for common operations
• Performance Metrics - Built-in tracking for request duration and success rates
• Read-Only Mode - Optional safety mode that blocks all write operations
• Toolset Filtering - Enable/disable specific tool categories as needed

Tool Categories

307 tools across 29 categories — complete coverage of the Pipedrive REST API (v1 + v2):

Category	Tools	Description
Deals	43	Full lifecycle: CRUD, stages, participants, products, files, merge, conversions, installments (v2)
Fields	30	Custom field discovery + CRUD for deal/person/org/product/project fields, plus lead & note fields
Persons	23	Contact management with custom fields, activities, deals, files, and followers
Organizations	21	Company management with relationships to persons, deals, and activities
Projects	16	Projects, boards, phases, groups, tasks, and plan management
Pipelines	15	Pipeline management, stages, conversion & movement statistics
Leads	15	Leads CRUD, labels, sources, search, and lead↔deal conversions
Roles	14	Roles, assignments, settings, and pipeline visibility
Products	13	Product catalog, deal/person attachments, files, and followers
Users	12	Users, permissions, followers, and role assignments
Notes	9	Notes and comments for deals, persons, and organizations
Activities	9	Task, call, and meeting scheduling with due dates and completion
System	9	Health, metrics, currencies, user settings, recents, and cache
Teams	8	Team management and membership
Files	7	File upload, download, management, and remote file linking
Filters	7	Filter CRUD and helper metadata
Search	6	Universal and entity-specific search
Mailbox	6	Mail threads and messages
Stages	5	Pipeline stage CRUD (v2)
Tasks	5	Project task management
Goals	5	Goal CRUD and results
Call logs	5	Call log CRUD and audio attachments
Activity types	5	Activity type management
Org relationships	5	Organization-to-organization relationships
Channels	4	Messaging channel integration
Webhooks	3	Webhook CRUD
Permission sets	3	Permission set inspection and assignments
Project templates	2	Project template discovery
Meetings	2	Video call provider linking

Installation

Global Installation

npm install -g @nubiia/mcp-pipedrive

Using npx (No Installation Required)

npx -y @nubiia/mcp-pipedrive

Configuration

Prerequisites

1. Get your Pipedrive API token from Settings > API
2. Have Claude Desktop installed

Claude Desktop Setup

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
PIPEDRIVE_API_TOKEN	Yes	-	Your Pipedrive API token
PIPEDRIVE_READ_ONLY	No	false	Enable read-only mode (blocks all write operations)
PIPEDRIVE_TOOLSETS	No	deals,persons,organizations,activities	Comma-separated list of enabled tool categories
LOG_LEVEL	No	info	Logging level (debug, info, warn, error)

Advanced Configuration Examples

Read-Only Mode

Perfect for exploratory use or when you want to prevent accidental modifications:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_READ_ONLY": "true"
      }
    }
  }
}

Filtered Toolsets

Only enable specific tool categories:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_TOOLSETS": "deals,persons,search"
      }
    }
  }
}

Debug Logging

Enable verbose logging for troubleshooting:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Usage Examples

Example 1: Creating a Deal with Contact

Claude, create a new deal for "Enterprise Software License" worth $50,000.
The contact is John Smith ([email protected]). Set the expected close date
to the end of next month and add a follow-up call for tomorrow.

Claude will:

1. Search for or create the person "John Smith"
2. Create the deal linked to this person
3. Schedule a call activity for tomorrow
4. Provide a summary with IDs and next steps

Example 2: Searching for Contacts

Find all contacts at Acme Corporation and show me their recent deals.

Claude will:

1. Search organizations for "Acme Corporation"
2. Get all persons associated with that organization
3. Retrieve deals for each person
4. Present organized results with totals

Example 3: Managing Activities

Show me all overdue activities for my open deals and reschedule them
to next week.

Claude will:

1. List all activities with done=false and past due dates
2. Filter for activities linked to open deals
3. Update each activity with new dates next week
4. Provide a summary of rescheduled items

Example 4: Using Custom Fields

Before creating this deal, show me what custom fields are available
for deals and explain what each one means.

Claude will:

1. Access the pipedrive://custom-fields resource
2. Extract deal-specific custom fields
3. Display field names, types, and options
4. Explain how to use them in deal creation

Example 5: Pipeline Management

Generate a pipeline report showing deal counts and total values for
each stage in my sales pipeline.

Claude will:

1. Use the pipedrive://pipelines resource
2. Get deal summaries grouped by stage
3. Calculate totals and percentages
4. Format as a readable report

Example 6: Weekly Review Workflow

Run the weekly pipeline review prompt.

Claude will:

1. Execute the weekly-pipeline-review prompt
2. Gather all open deals by stage
3. Calculate metrics (won/lost, approaching close, stale deals)
4. Generate actionable recommendations

Custom fields

Pass custom field values by display name when creating or updating deals, persons, organizations, products, or leads:

{
  "title": "ACME Enterprise Deal",
  "value": 50000,
  "currency": "USD",
  "custom_fields": {
    "Industria": "Tech",
    "Budget": 50000
  }
}

The MCP server resolves names to Pipedrive hash keys automatically. See docs/CUSTOM_FIELDS.md for the full guide.

Stage and lead-label management

Manage pipeline stages and lead labels directly from the LLM:

{ "name": "Qualified", "pipeline_id": 1, "deal_probability": 75 }

Convert qualified leads into deals (or roll a deal back to a lead) via the asynchronous *_convert_to_* / *_convert_status tool pairs.

Deal installments

Manage scheduled, fixed payments on a deal (API v2 — the modern replacement for the legacy subscriptions feature):

{ "id": 123, "description": "Deposit", "amount": 500, "billing_date": "2026-01-15" }

Tools: deals_list_installments, deals_add_installment, deals_update_installment, deals_delete_installment.

Full field coverage

Field tools now cover every entity: deal, person, organization, product, lead and note field listings (fields_list_lead_fields, fields_list_note_fields — read-only), plus full project field CRUD via API v2 (fields_list_project_fields, fields_create_project_field, fields_update_project_field, fields_delete_project_field).

Architecture

Core Components

• PipedriveClient - HTTP client with rate limiting, caching, and retry logic
• Rate Limiter - Bottleneck-based limiter (10 req/s, burst capacity)
• Cache Layer - TTL-based cache with LRU eviction (500 item max)
• Retry Handler - Exponential backoff for transient failures
• Metrics Collector - Request tracking and performance monitoring
• Error Handler - Standardized error formatting with context

Tool Structure

Each tool follows a consistent pattern:

1. Zod Schema - Input validation with descriptive errors
2. Description - Detailed usage instructions for the LLM
3. Handler - Async function that calls PipedriveClient

Resources

Three MCP resources provide read-only reference data:

• pipedrive://pipelines - All pipelines with stages and deal counts
• pipedrive://custom-fields - Custom field definitions for all entities
• pipedrive://current-user - Authenticated user info and permissions

Prompts

Five guided workflows for common operations:

• create-deal-workflow - Complete deal creation with person and activity
• sales-qualification - BANT qualification checklist
• follow-up-sequence - Multi-day activity sequence
• weekly-pipeline-review - Pipeline health report
• lost-deal-analysis - Lost deal pattern analysis

Performance

Rate Limiting

• Default: 10 requests/second (100ms between requests)
• Burst: 100 token reservoir that refills every minute
• Auto-retry: 429 errors automatically retry after 5 seconds

Caching Strategy

Data Type	TTL	Reason
Pipelines	10 min	Pipeline structures change infrequently
Custom Fields	15 min	Field definitions are relatively static
User Info	1 min	User data may change during session
List Requests	5 min	Default for paginated results

Metrics

The server tracks:

• Total requests and success rate
• Average response time
• Error rate by type
• Cache hit rate
• Rate limit events

Access metrics with the system/metrics tool.

API Reference

This MCP server implements the Pipedrive REST API v1. For detailed API documentation, see:

• Pipedrive API Reference
• Pipedrive API Changelog
• Rate Limits

Advanced Usage

Custom Field Discovery

Before creating or updating entities, check available custom fields:

// Access via MCP resource
//custom-fields

// Or use field tools
pipedrive: fields / deal - fields;
fields / person - fields;
fields / org - fields;
fields / activity - fields;

Error Handling

All tools return structured errors with:

• Error type (validation, authentication, rate limit, etc.)
• Detailed message
• Suggested actions
• Original API error (if applicable)

Workflow Automation

Chain multiple tools together for complex workflows:

1. Lead Qualification

   • Search for person
   • Get their deals and activities
   • Create qualification note
   • Update deal stage

2. Deal Pipeline Movement

   • Get deal details
   • Check custom field requirements
   • Update custom fields
   • Move to next stage
   • Create next activity

3. Reporting

   • List deals by stage
   • Get deal summaries
   • Calculate metrics
   • Format as markdown

Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

Quick fixes:

• Authentication errors: Verify your API token at https://app.pipedrive.com/settings/api
• Rate limiting: Reduce request frequency or enable caching
• Validation errors: Check tool input schema and required fields
• Not seeing tools in Claude: Restart Claude Desktop after config changes

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/nubiia-dev/mcp-pipedrive.git
cd mcp-pipedrive

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run with auto-reload during development
npm run dev

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run with UI
npm run test:ui

Security

Please see SECURITY.md for our security policy and how to report vulnerabilities.

Important: Never commit your API token to version control. Always use environment variables.

About Nubiia

This MCP server is built and maintained by Nubiia.

Nubiia ayuda a empresas a automatizar procesos e integrar sus herramientas con IA: servidores MCP a medida, integraciones con CRMs y ERPs (Pipedrive, Holded y más), y agentes que conectan tus datos de negocio con asistentes como Claude. Este @nubiia/mcp-pipedrive es un ejemplo open source de lo que hacemos.

👉 ¿Quieres una integración o automatización con IA para tu negocio? nubiia.es · ✉️ [email protected]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Inspired by mcp-holded - an excellent MCP server implementation for Holded CRM.

Support

• Nubiia — AI automation & integrations: nubiia.es
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

Changelog

See CHANGELOG.md for version history and release notes.

Roadmap

• Webhook support for real-time updates
• Bulk operations for mass updates
• Advanced filtering with complex queries
• Export/import functionality
• Integration with other CRMs
• GraphQL support

Author

Built by Nubiia — nubiia.es · [email protected]

Maintainer: Samuel Fraga — GitHub

---

Made with dedication by Nubiia