pipedrive-mcp-server

# Pipedrive MCP Server

[![npm version](https://img.shields.io/npm/v/@ckalima/pipedrive-mcp-server?logo=npm)](https://www.npmjs.com/package/@ckalima/pipedrive-mcp-server)
[![CI](https://github.com/ckalima/pipedrive-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ckalima/pipedrive-mcp-server/actions/workflows/ci.yml)
[![tests](https://img.shields.io/badge/tests-1%2C700%2B%20passing-brightgreen)](https://github.com/ckalima/pipedrive-mcp-server/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](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):

```bash
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:

```json
{
  "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:

```bash
npx -y @ckalima/pipedrive-mcp-server
```

Or set the environment variable:

```bash
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

<!-- BEGIN GENERATED 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.

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

### 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 disco