Enables Claude to manage sales workflows, deals, contacts, and pipelines through comprehensive access to the Pipedrive CRM API.
Also known as nubiia-dev/mcp-pipedrive, @nubiia/mcp-pipedrive
- Stars
- 12
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2.7.1
- Last commit
- Oct 22, 2026
- License
- MIT
What is Pipedrive MCP?
Pipedrive enables Claude to manage sales workflows, deals, contacts, and pipelines through comprehensive access to the Pipedrive CRM API.
Summary generated from the project's README
About Pipedrive MCP server
Managing sales pipelines and contact information through natural language is what this server enables for sales professionals using Claude. It provides a direct connection to the Pipedrive CRM API, allowing users to automate workflows, organize deals, and track activities without manual data entry. The server can be installed globally via npm or run using npx for local execution within the Claude Desktop environment.
Users must provide a Pipedrive API token via environment variables to establish a connection. The implementation includes over 300 tools across 29 categories, covering everything from lead conversion and deal management to product catalogs and organization relationships. To ensure safety, a read-only mode is available to block all write operations, and users can filter specific toolsets to limit the available commands. The system also features advanced rate limiting, multi-level caching, and exponential backoff for handling failed requests.
What you can do with it
- 1Automate deal and contact creationCreate a new deal for a specific client while simultaneously setting up the contact and scheduling a follow-up call.
- 2Perform deep contact researchIdentify all individuals associated with a specific company and retrieve their recent sales history.
- 3Reschedule overdue sales activitiesIdentify all past due tasks linked to active deals and move them to a future date.
- 4Generate pipeline performance reportsProduce a summary of deal counts and total monetary values organized by their current pipeline stage.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pipedrive MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pipedrive MCP in Claude Code
$ claude mcp add --env 'PIPEDRIVE_API_TOKEN=<YOUR_PIPEDRIVE_API_TOKEN>' --env 'PIPEDRIVE_COMPANY_DOMAIN=<PIPEDRIVE_COMPANY_DOMAIN>' mcp-pipedrive -- npx -y @nubiia/mcp-pipedriveInstall Pipedrive MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-pipedrive": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-pipedrive"
],
"env": {
"PIPEDRIVE_API_TOKEN": "<YOUR_PIPEDRIVE_API_TOKEN>",
"PIPEDRIVE_COMPANY_DOMAIN": "<PIPEDRIVE_COMPANY_DOMAIN>"
}
}
}
}Install Pipedrive MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-pipedrive": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-pipedrive"
],
"env": {
"PIPEDRIVE_API_TOKEN": "<YOUR_PIPEDRIVE_API_TOKEN>",
"PIPEDRIVE_COMPANY_DOMAIN": "<PIPEDRIVE_COMPANY_DOMAIN>"
}
}
}
}Install Pipedrive MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-pipedrive","type":"stdio","command":"npx","args":["-y","@nubiia/mcp-pipedrive"],"env":{"PIPEDRIVE_API_TOKEN":"<YOUR_PIPEDRIVE_API_TOKEN>","PIPEDRIVE_COMPANY_DOMAIN":"<PIPEDRIVE_COMPANY_DOMAIN>"}}'Install Pipedrive MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-pipedrive": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-pipedrive"
],
"env": {
"PIPEDRIVE_API_TOKEN": "<YOUR_PIPEDRIVE_API_TOKEN>",
"PIPEDRIVE_COMPANY_DOMAIN": "<PIPEDRIVE_COMPANY_DOMAIN>"
}
}
}
}Install Pipedrive MCP in Codex
$ codex mcp add mcp-pipedrive --env 'PIPEDRIVE_API_TOKEN=<YOUR_PIPEDRIVE_API_TOKEN>' --env 'PIPEDRIVE_COMPANY_DOMAIN=<PIPEDRIVE_COMPANY_DOMAIN>' -- npx -y @nubiia/mcp-pipedriveInstall Pipedrive MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-pipedrive] command = "npx" args = ["-y", "@nubiia/mcp-pipedrive"] [mcp_servers.mcp-pipedrive.env] PIPEDRIVE_API_TOKEN = "<YOUR_PIPEDRIVE_API_TOKEN>" PIPEDRIVE_COMPANY_DOMAIN = "<PIPEDRIVE_COMPANY_DOMAIN>"
Install Pipedrive MCP in Gemini CLI
$ gemini mcp add -s user -e 'PIPEDRIVE_API_TOKEN=<YOUR_PIPEDRIVE_API_TOKEN>' -e 'PIPEDRIVE_COMPANY_DOMAIN=<PIPEDRIVE_COMPANY_DOMAIN>' mcp-pipedrive npx -- -y @nubiia/mcp-pipedriveInstall Pipedrive MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-pipedrive": {
"command": "npx",
"args": [
"-y",
"@nubiia/mcp-pipedrive"
],
"env": {
"PIPEDRIVE_API_TOKEN": "<YOUR_PIPEDRIVE_API_TOKEN>",
"PIPEDRIVE_COMPANY_DOMAIN": "<PIPEDRIVE_COMPANY_DOMAIN>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Configuration
PIPEDRIVE_API_TOKENRequiredSecretYour Pipedrive API token (found in Settings → Personal Preferences → API)
PIPEDRIVE_COMPANY_DOMAINRequiredYour Pipedrive company domain (e.g., 'mycompany' if your URL is mycompany.pipedrive.com)
LOG_LEVELPIPEDRIVE_READ_ONLYSet to 'true' to enable read-only mode (blocks all write operations)
PIPEDRIVE_TOOLSETSComma-separated list of toolsets to enable (e.g., 'deals,persons,organizations')
| Name | Description | |
|---|---|---|
| PIPEDRIVE_API_TOKEN | Your Pipedrive API token (found in Settings → Personal Preferences → API) | RequiredSecret |
| PIPEDRIVE_COMPANY_DOMAIN | Your Pipedrive company domain (e.g., 'mycompany' if your URL is mycompany.pipedrive.com) | Required |
| LOG_LEVEL | — | |
| PIPEDRIVE_READ_ONLY | Set to 'true' to enable read-only mode (blocks all write operations) | |
| PIPEDRIVE_TOOLSETS | Comma-separated list of toolsets to enable (e.g., 'deals,persons,organizations') |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubPipedrive 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
- Get your Pipedrive API token from Settings > API
- 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 (john@acme.com). Set the expected close date
to the end of next month and add a follow-up call for tomorrow.
Claude will:
- Search for or create the person "John Smith"
- Create the deal linked to this person
- Schedule a call activity for tomorrow
- 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:
- Search organizations for "Acme Corporation"
- Get all persons associated with that organization
- Retrieve deals for each person
- 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:
- List all activities with
done=falseand past due dates - Filter for activities linked to open deals
- Update each activity with new dates next week
- 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:
- Access the
pipedrive://custom-fieldsresource - Extract deal-specific custom fields
- Display field names, types, and options
- 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:
- Use the
pipedrive://pipelinesresource - Get deal summaries grouped by stage
- Calculate totals and percentages
- Format as a readable report
Example 6: Weekly Review Workflow
Run the weekly pipeline review prompt.
Claude will:
- Execute the
weekly-pipeline-reviewprompt - Gather all open deals by stage
- Calculate metrics (won/lost, approaching close, stale deals)
- 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:
- Zod Schema - Input validation with descriptive errors
- Description - Detailed usage instructions for the LLM
- Handler - Async function that calls PipedriveClient
Resources
Three MCP resources provide read-only reference data:
pipedrive://pipelines- All pipelines with stages and deal countspipedrive://custom-fields- Custom field definitions for all entitiespipedrive://current-user- Authenticated user info and permissions
Prompts
Five guided workflows for common operations:
create-deal-workflow- Complete deal creation with person and activitysales-qualification- BANT qualification checklistfollow-up-sequence- Multi-day activity sequenceweekly-pipeline-review- Pipeline health reportlost-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:
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:
-
Lead Qualification
- Search for person
- Get their deals and activities
- Create qualification note
- Update deal stage
-
Deal Pipeline Movement
- Get deal details
- Check custom field requirements
- Update custom fields
- Move to next stage
- Create next activity
-
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 · ✉️ hola@nubiia.es
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 · hola@nubiia.es
Maintainer: Samuel Fraga — GitHub
Made with dedication by Nubiia
Pipedrive MCP questions
How do I add Pipedrive MCP to Claude Code?
Run claude mcp add --env 'PIPEDRIVE_API_TOKEN=<YOUR_PIPEDRIVE_API_TOKEN>' --env 'PIPEDRIVE_COMPANY_DOMAIN=<PIPEDRIVE_COMPANY_DOMAIN>' mcp-pipedrive -- npx -y @nubiia/mcp-pipedrive in your terminal. Add --scope user to make it available in every project.
How do I add Pipedrive MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use this server in a safe mode to prevent accidental changes?
Yes, you can enable a Read-Only mode that blocks all write operations.
Can I limit which tools the AI can access?
Yes, you can use the PIPEDRIVE_TOOLSETS environment variable to enable or disable specific tool categories.