ckalima/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.
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.
- **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.
- **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):
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:
> **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:
Or set the environment variable:
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. |
| 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. |