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 | 123 | 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 32 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 123, 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?"

## Connected account

The API token decides which Pipedrive company you are talking to, and until now nothing in a tool result said which one that was. Two registrations of this server in the same client (say, a project-scoped entry and a local-scoped one that reads a stale `.env`) resolve to different companies, and the one that loses precedence is invisible. The server now names the account it actually resolved, in two places.

**On startup**, one line on stderr:

```
[pipedrive-mcp-server] Connected as you@example.com -> company "Example Corp" (id 12345)
```

If the check fails, that line says so (`Could not verify connected account: ...`) instead of the server starting silently. If the API key is missing or malformed it reports that the account was not checked, because no request was made.

**On the first tool response after the boot check settles**, a one-shot `connection` block naming the same company, so the agent knows which account the data came from without being asked and without spending a tool call. It is emitted once per process. The check runs in the background, so any tool call that finishes while it is still in flight is returned unchanged and the block lands on a later response instead. Treat it as a fact the server volunteers once it knows, not as a guarantee that every early response carries it. Delivery is also not consumption: a host that passes the block through unchanged still leaves it to the model whether to act on it, and smaller models skip it on some runs.

Inside that block, `company_id` and `verified` are asserted by the server and sit at the top level. The display strings the server cannot vouch for - `company_name` and `user_email`, or `reason` when the check did not succeed - are nested under `untrusted_display`, because a company name is CRM content that anyone with write access to the account can set. If you parse the block, bind everything under that key to the same trust level you give `data`. See [SECURITY.md](SECURITY.md#prompt-injection-u