Pipedrive Mcp Server

Pipedrive MCP Server

[](https://www.npmjs.com/package/@ckalima/pipedrive-mcp-server) [](https://github.com/ckalima/pipedrive-mcp-server/actions/workflows/ci.yml) [](https://github.com/ckalima/pipedrive-mcp-server/actions/workflows/ci.yml) [](LICENSE)

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.

Why this server

• API v2-first. Every entity uses Pipedrive's v2 REST API where it exists; v1 is used only for the capabilities that have no v2 equivalent (notes, mail, users, and leads CRUD). See [API Versioning](#api-versioning).
• Contract-tested against the real OpenAPI spec. Request params, request bodies, and response shapes are checked against the vendored Pipedrive OpenAPI v2 definition (docs/api/openapi-v2.yaml) in tests/contract/, so the v2 tools can't silently drift from the documented API.
• Live-smoke verified. The tool surface is broadly exercised against a real Pipedrive account (scripts/smoke-coverage.ts), with only API-unseedable surfaces (e.g. mail threads, project templates) left to manual checks. Coverage includes plan-gated endpoints such as Growth+ deal installments (scripts/smoke-installments.ts). Key write smokes (e.g. the task is_done flag) assert the field value actually changed on the wire, not just a 200.
• Server-enforced capability modes. PIPEDRIVE_MODE picks a safety tier — read-only, safe-write (the default: reads + non-destructive writes), or full — and out-of-mode tools are both hidden from tools/list and refused if called directly. Deletes, conversions, and other irreversible writes (🔒 in the tool table) require full, so the server is read-and-create only out of the box. Every tool also carries MCP annotations (readOnlyHint/destructiveHint/idempotentHint) so policy-aware clients can tell reads from writes from deletes. See [Capability modes](#capability-modes).
• MIT licensed, published with npm build provenance.

Honest limitations. Transport is STDIO only today (a Streamable HTTP flag is planned), and auth is via a Pipedrive API key, which matches the local/self-hosted tier this server targets. There is no hosted OAuth offering yet.

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

Fastest setup: npx … init

Run the one-command guided installer and follow the prompts. It opens the Pipedrive API-token page, validates your key live against your account, and generates a working MCP config for your client (Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code):

npx -y @ckalima/pipedrive-mcp-server init

It always prints a paste-ready block and can optionally write it into your client's config file after a timestamped backup. Committed/shared config files use ${PIPEDRIVE_API_KEY} indirection, never a raw key. Prefer to configure by hand? The manual steps below still work.

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", "@ckalima/pipedrive-mcp-server"],
      "env": {
        "PIPEDRIVE_API_KEY": "your-40-character-api-key"
      }
    }
  }
}

> Package name: the supported package is the scoped @ckalima/pipedrive-mcp-server. If you arrived from an older snippet that referenced the unscoped pipedrive-mcp-server, update your config to the scoped name above — the unscoped name is a different, unrelated package.

You can also start it directly to verify your setup:

npx -y @ckalima/pipedrive-mcp-server

Or set the environment variable:

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

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PIPEDRIVE_API_KEY | Yes | - | Your 40-character Pipedrive API token. | | PIPEDRIVE_MODE | No | safe-write | Server-enforced capability tier: read-only (reads only), safe-write (reads + non-destructive writes), or full (all tools, including destructive). Out-of-mode tools are hidden from tools/list and refused if called directly. Authoritative when set to a recognized value; a blank value is treated as unset (the default applies), an unrecognized value falls back to read-only. See [Capability modes](#capability-modes). | | PIPEDRIVE_ENABLE_DESTRUCTIVE | No | false | Legacy flag, superseded by PIPEDRIVE_MODE. When PIPEDRIVE_MODE is unset, true is treated as full and anything else as safe-write. Still honored for back-compat; prefer PIPEDRIVE_MODE=full. | | PIPEDRIVE_IMAGE_BASE_DIR | No | (unset) | Allowlisted directory the server may read product images from when file_path is passed to the image-upload tools. Filesystem reads are disabled unless this is set, and a file_path must resolve within it. Leave unset and pass base64_data if the caller cannot share the server's filesystem. See [SECURITY.md](SECURITY.md#operator-best-practices). |

To enable destructive tools, set PIPEDRIVE_MODE=full (or, for back-compat, PIPEDRIVE_ENABLE_DESTRUCTIVE=true) in the env block of your .mcp.json alongside PIPEDRIVE_API_KEY. Below full, every 🔒 tool returns a DESTRUCTIVE_DISABLED error instead of acting, and tools above the active tier return a MODE_RESTRICTED error.

Capability modes

PIPEDRIVE_MODE sets a server-enforced safety tier. The tier is enforced two ways: out-of-mode tools are filtered out of tools/list (so the agent never sees them) and the dispatcher refuses any out-of-mode call by name before its handler runs, so the tier is a real guarantee rather than a UI hint.

| Mode | What's available | Tools | Destructive ops | |------|------------------|------:|-----------------| | read-only | read verbs only (list/get/search) | 69 | no | | safe-write | reads + non-destructive writes | 124 | no | | full | all tools | 155 | yes |

Recommended for first-time setup and agent evaluation: read-only. Let the agent look before it can touch anything, then widen the tier as you build trust.

Backward compatibility. PIPEDRIVE_MODE is authoritative when set. When it is unset, the mode is derived from the legacy PIPEDRIVE_ENABLE_DESTRUCTIVE flag (true → full, otherwise safe-write), so existing installs keep their execution behavior on upgrade: every tool that ran before still runs, and every tool gated before is still gated. The one observable change at the unset default (safe-write) is that the 31 destructive tools — already refused at execution unless enabled — are now also hidden from tools/list rather than listed-then-refused (so the listed surface is 124, not 155). An unrecognized PIPEDRIVE_MODE value falls back to read-only.

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

155 tools. 🔒 destructive (require PIPEDRIVE_MODE=full, off by default) · ⭑ requires a Growth+ plan. The active [capability mode](#capability-modes) governs which tools are listed.

This section is generated by npm run gen:docs from the live tool registry. Do not edit by hand - CI fails on drift.

Deals

| Tool | Description | |------|-------------| | pipedrive_list_deals | List deals from Pipedrive with optional filtering by owner, person, organization, pipeline, stage, or status. Returns paginated results. | | pipedrive_get_deal | Get detailed information about a specific deal by ID, including all standard and custom fields. | | pipedrive_create_deal | Create a new deal in Pipedrive. Only title is required; all other fields are optional. | | pipedrive_update_deal | Update an existing deal in Pipedrive. Specify the deal ID and any fields to update. | | pipedrive_search_deals | Search for deals by text in title. Supports fuzzy matching by default. | | pipedrive_delete_deal 🔒 | Delete a deal. The deal will be marked as deleted and permanently removed after 30 days. | | pipedrive_list_deal_followers | List all followers for a deal. | | pipedrive_add_deal_follower | Add a follower to a deal. | | pipedrive_delete_deal_follower 🔒 | Remove a follower from a deal. | | pipedrive_get_deal_followers_changelog | Get the followers changelog for a deal. | | pipedrive_list_deal_products | List line-item products attached to a deal. Returns paginated results. | | pipedrive_add_deal_product | Attach a single product as a line item to a deal. | | pipedrive_update_deal_product | Update a line-item product attached to a deal. All body fields optional. | | pipedrive_delete_deal_product 🔒 | Remove a line-item product from a deal. | | pipedrive_bulk_add_deal_products | Bulk-add up to 100 line-item products to a deal in one request. | | pipedrive_list_deal_discounts | List all additional discounts applied to a deal. | | pipedrive_add_deal_discount | Add an additional discount to a deal. | | pipedrive_update_deal_discount | Update an additional discount on a deal. All fields except IDs are optional. | | pipedrive_delete_deal_discount 🔒 | Delete an additional discount from a deal. | | pipedrive_list_deal_installments ⭑ | List installments across one or more deals. Requires dealids. Growth+ plan required. | | pipedrive_add_deal_installment ⭑ | Add an installment (payment schedule entry) to a deal. Growth+ plan required; the deal must have at least one one-time product and no recurring products. | | pipedrive_update_deal_installment ⭑ | Update an installment on a deal. Growth+ plan required; all body fields optional. | | pipedrive_delete_deal_installment 🔒 ⭑ | Delete an installment from a deal. Growth+ plan required. | | pipedrive_list_archived_deals | List archived deals with the same filtering as the active deals list (owner, person, organization, pipeline, stage, status). Returns paginated results. | | pipedrive_convert_deal_to_lead 🔒 | Convert a deal to a lead (async job). DESTRUCTIVE: a successful conversion marks the source deal as deleted. Returns a conversionid; the conversion runs asynchronously, so you MUST poll pipedrivegetdealconversionstatus with the conversionid until a terminal status. Requires PIPEDRIVEMODE=full (back-compat: PIPEDRIVEENABLEDESTRUCTIVE=true). | | pipedrive_get_deal_conversion_status | Get the status of a deal-to-lead conversion job. Status contract: 'completed' (terminal, carries leadid), 'failed'/'rejected' (terminal, stop polling, no lead produced), 'notstarted'/'running' (in-progress, re-poll). Only 'completed' carries lead_id, and conversion status is purged after a few days, so a 404 returned after a prior valid status means the status was purged (terminal stop-polling signal, not a transient error). Use a bounded poll budget (e.g. up to ~6 attempts with short backoff), not an unbounded loop. |

Persons

| Tool | Description | |------|-------------| | pipedrive_list_persons | List persons (contacts) from Pipedrive with optional filtering by owner, organization, or first letter of name. | | pipedrive_get_person | Get detailed information about a specific person by ID. | | pipedrive_create_person | Create a new person (contact) in Pipedrive. Only name is required. | | pipedrive_update_person | Update an existing person in Pipedrive. | | pipedrive_search_persons | Search for persons by name, email, or phone number. | | pipedrive_delete_person 🔒 | Delete a person. The person will be marked as deleted and permanently removed after 30 days. | | pipedrive_list_person_followers | List all followers for a person. | | pipedrive_add_person_follower | Add a follower to a person. | | pipedrive_delete_person_follower 🔒 | Remove a follower from a person. | | pipedrive_get_person_followers_changelog | Get the followers changelog for a person. | | pipedrive_get_person_picture | Get the picture for a person (read-only; returns picture metadata and sized image URLs). Returns an error if the person has no picture. |

Organizations

| Tool | Description | |------|-------------| | pipedrive_list_organizations | List organizations from Pipedrive with optional filtering by owner or first letter of name. | | pipedrive_get_organization | Get detailed information about a specific organization by ID. | | pipedrive_create_organization | Create a new organization in Pipedrive. Only name is required. | | pipedrive_update_organization | Update an existing organization in Pipedrive. | | pipedrive_search_organizations | Search for organizations by name or address. | | pipedrive_delete_organization 🔒 | Delete an organization. The organization will be marked as deleted and permanently removed after 30 days. | | pipedrive_list_organization_followers | List all followers for an organization. | | pipedrive_add_organization_follower | Add a follower to an organization. | | pipedrive_delete_organization_follower 🔒 | Remove a follower from an organization. | | pipedrive_get_organization_followers_changelog | Get the followers changelog for an organization. |

Activities

| Tool | Description | |------|-------------| | pipedrive_list_activities | List activities from Pipedrive with optional filtering by owner, deal, person, organization, type, or completion status. | | pipedrive_get_activity | Get detailed information about a specific activity by ID. | | pipedrive_create_activity | Create a new activity in Pipedrive. Subject and type are required. | | pipedrive_update_activity | Update an existing activity in Pipedrive. Use this to mark activities as done. | | pipedrive_delete_activity 🔒 | Delete an activity. |

Notes

| Tool | Description | |------|-------------| | pipedrive_list_notes | List notes from Pipedrive with optional filtering by deal, person, organization, or lead. | | pipedrive_get_note | Get detailed information about a specific note by ID. | | pipedrive_create_note | Create a new note in Pipedrive. Content is required. Link to a deal, person, organization, or lead. | | pipedrive_update_note | Update an existing note in Pipedrive. | | pipedrive_delete_note 🔒 | Delete a note. |

Leads

| Tool | Description | |------|-------------| | pipedrive_list_leads | List active (non-archived) leads from Pipedrive with optional filtering by owner, person, or organization. | | pipedrive_list_archived_leads | List archived leads from Pipedrive with optional filtering by owner, person, or organization. | | pipedrive_get_lead | Get detailed information about a specific lead by UUID. | | pipedrive_create_lead | Create a new lead in Pipedrive. Title is required; link to at least one of personid or organizationid. | | pipedrive_update_lead | Update an existing lead in Pipedrive. | | pipedrive_search_leads | Search for leads in Pipedrive by title or associated contacts. | | pipedrive_delete_lead 🔒 | Delete a lead. Requires PIPEDRIVEMODE=full (back-compat: PIPEDRIVEENABLE_DESTRUCTIVE=true). | | pipedrive_convert_lead_to_deal | Convert a lead into a deal (Pipedrive v2). The conversion runs asynchronously; this tool polls until it completes (typically under 5s) and returns the new deal ID. If it is s

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ckalima
• Source: ckalima/pipedrive-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.