Pipedrive MCP Server

An MCP (Model Context Protocol) server for Pipedrive CRM integration with Claude Code and Claude Desktop. Query, create, and update CRM data directly from your AI assistant.

Features

• Full CRM Operations: Deals, persons, organizations, activities
• Email Analysis: Access mail threads and messages for engagement analysis
• Field Discovery: Map custom field hash codes to human-readable names
• Pipeline Management: List pipelines, stages, and users
• Pagination Support: Cursor-based pagination for large datasets
• Error Handling: Clear, actionable error messages

Quick Start

1. Get Your Pipedrive API Key

1. Log into Pipedrive
2. Go to Settings > Personal preferences > API
3. Copy your API key (40 characters)

2. Configure Claude Code

Add to your .mcp.json file:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "pipedrive-mcp-server"],
      "env": {
        "PIPEDRIVE_API_KEY": "your-40-character-api-key"
      }
    }
  }
}

Or set the environment variable:

export PIPEDRIVE_API_KEY="your-40-character-api-key"

3. Start Using

Once configured, Claude can access your Pipedrive data:

• "Show me open deals worth more than $10,000"
• "Create a deal called 'Acme Contract' with value $50,000"
• "Find all contacts at TechCorp"
• "List recent email threads in my inbox"
• "What custom fields are defined for deals?"

Available Tools

Core CRM Operations (Tier 1)

Email/Mail Tools (Tier 2)

Field Metadata (Tier 3)

Supporting Resources (Tier 4)

Example Workflows

Analyze Deal Pipeline

"Show me all open deals in the Sales pipeline, sorted by value"
"Get details for deal 12345 including custom fields"
"Move deal 12345 to the Proposal stage"

Customer Research

"Find contacts at Acme Corp"
"Get emails for person 456 to analyze their engagement"
"What custom fields do we have for persons?"

Activity Management

"List my overdue activities"
"Create a follow-up call with John Smith for tomorrow at 2pm"
"Mark activity 789 as done"

Field Discovery

"List all custom fields for deals"
"What does field '8a4d7f...' mean?" (40-char hash)

Development

Local Setup

git clone https://github.com/ckalima/pipedrive-mcp-server.git
cd pipedrive-mcp-server
npm install
cp .env.example .env
# Edit .env with your API key

Build & Run

npm run build
npm run start

Development Mode

npm run dev

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

API Versioning

This server uses both Pipedrive API versions:

• v2 (/api/v2): Deals, Persons, Organizations, Activities
• v1 (/v1): Mail, Fields, Pipelines, Stages, Users

The client automatically routes to the correct version.

Error Handling

Errors are returned with actionable suggestions:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or expired",
    "suggestion": "Verify your API key at Pipedrive Settings > Personal preferences > API"
  }
}

Common error codes:

• MISSING_API_KEY - Set PIPEDRIVE_API_KEY environment variable
• INVALID_API_KEY - Check your API key in Pipedrive settings
• NOT_FOUND - The requested resource doesn't exist
• RATE_LIMITED - Wait 60 seconds before retrying
• VALIDATION_ERROR - Check your request parameters

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE

Links

• Pipedrive API Documentation
• MCP Protocol
• Report Issues