pipedrive-mcp

# pipedrive-mcp

[![CI](https://github.com/mmedum/pipedrive-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mmedum/pipedrive-mcp/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/mmedum/pipedrive-mcp?sort=semver)](https://github.com/mmedum/pipedrive-mcp/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/mmedum/pipedrive-mcp.svg)](https://pkg.go.dev/github.com/mmedum/pipedrive-mcp)
[![License: Apache 2.0](https://img.shields.io/github/license/mmedum/pipedrive-mcp)](./LICENSE)

Pipedrive CRM as MCP tools. Find deals, people and companies, write to them, and move deals through a pipeline.

A single Go binary that speaks [Model Context Protocol](https://modelcontextprotocol.io)
over stdio — protocol revisions `2026-07-28` (the current one) back to
`2024-11-05`, negotiated per client. It runs as a subprocess of your client, on your own machine,
against one Pipedrive workspace: search by name and get back the ids
everything else needs, read deals, people, organisations, activities and
notes with their custom fields under the names your workspace gives them
and dropdown values under their labels, create and edit any of them, and
move a deal through its pipeline — won, lost, reopened, or into another
stage.

## Why pipedrive-mcp

Pipedrive's own API is two APIs: a v2 that is current and a v1 whose
sunset date, 2026-07-31, **has passed**. This server commits to v2 and
carves out only what exists nowhere else — notes, and the `whoami`
lookup. Those four tools run on an API that is out of support; they
still answer, and there is no v2 to move them to, because v2 exposes no
`/notes` and no `/users`. Both carve-outs are documented at their call
sites and in [CHANGELOG.md](CHANGELOG.md), because a v1 dependency
nobody wrote down is one nobody migrates — and a 410 from either now
reaches you as `[gone]`, naming the sunset, rather than as a validation
error blaming your request.

Its tool surface follows the shipped Google Workspace MCP servers rather
than a house style of its own: reads stay discrete, every mutation goes
through one `manage_` tool with an `action`, and writes explain their
refusals. Those are the servers a model has most likely already seen, so
matching them is what makes this one legible without being explained.

**Writing is guarded because Pipedrive has no undo.** Every write reads
its target first and refuses to replace a field that already holds a
value unless you say so, naming each field it is protecting. A refusal
you cannot act on is a bug.

Every tool below is driven against a real Pipedrive workspace as well as
against the fakes the tests use — reads, resources, the guard refusals,
the rehearsal paths, and a reversible write on each resource that has
one. That rundown is a Go suite rather than a habit now: it lives in
`internal/integration/` behind `-tags=integration`, and `make
integration` runs it. Two things still bound it. The write probes need
a second opt-in on top of the tag, `PIPEDRIVE_INTEGRATION_WRITES=1`, so
a run without that proves the read half only — writing to a live CRM is
a decision, not a default. And it has been exercised against one
workspace, so a custom-field or permission setup unlike that one is
untested ground.

## Install

```
go install github.com/mmedum/pipedrive-mcp/cmd/pipedrive-mcp@latest
```

That puts the binary in Go's bin directory, which is often not on your
`PATH`. If the next command says `command not found`, either use the full
path or add the directory once:

```
"$(go env GOPATH)/bin/pipedrive-mcp" --version    # check it landed
export PATH="$(go env GOPATH)/bin:$PATH"          # or add it to your shell profile
```

Or take a signed archive from the
[latest release](https://github.com/mmedum/pipedrive-mcp/releases/latest)
— Linux, macOS and Windows, on amd64 and arm64 — and put the binary on
your `PATH`. Nothing about a release has to be taken on trust:

```bash
# --ignore-missing, because SHA256SUMS covers every archive and every
# SBOM, and you will have downloaded one of them.
sha256sum -c SHA256SUMS --ignore-missing

# One signature over the checksum file, keyless, tied to the release
# workflow's own identity.
cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.bundle \
  --certificate-identity-regexp 'https://github.com/mmedum/pipedrive-mcp/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

# And the archive itself carries build provenance.
gh attestation verify pipedrive-mcp-X.Y.Z-linux-amd64.tar.gz --owner mmedum
```

## Set up Pipedrive

The server stores your API token in the **OS keyring** (libsecret on
Linux, Keychain on macOS, Credential Manager on Windows) rather than
asking you to paste it into a JSON config. Full reference and
validation rules: [docs/configuration.md](docs/configuration.md).

```sh
pipedrive-mcp login
# Pipedrive workspace subdomain (e.g. acme for acme.pipedrive.com): your-subdomain
# Pipedrive API token for "your-subdomain": ········
# login: token stored in OS keyring (service=pipedrive-mcp, account=your-subdomain)
# login: default domain recorded in ~/.config/pipedrive-mcp/config.json
```

Pass `--domain your-subdomain` (or set `PIPEDRIVE_COMPANY_DOMAIN`) to
skip the domain prompt — useful in scripts.

After that, your MCP client config needs nothing about the workspace
domain or the token — both are resolved from the keyring + a small
non-secret pointer file (`os.UserConfigDir()/pipedrive-mcp/config.json`).
Run `pipedrive-mcp status` to verify, or `pipedrive-mcp logout` to
clear them.

To override the recorded domain in one shell (e.g. point at a
different workspace temporarily), set `PIPEDRIVE_COMPANY_DOMAIN` —
env wins over the userconfig pointer. For CI, automation, or one-off
use of a different token, set `PIPEDRIVE_API_TOKEN`. Env takes
precedence over the keyring, matching the `gh` and `aws` CLIs.


## Connect a client

### Claude Desktop

After `pipedrive-mcp login` has stored the token in your keyring AND
recorded the default domain in user-config, the Claude Desktop config
needs nothing — no secret, no domain:

```json
{
  "mcpServers": {
    "pipedrive": {
      "command": "/usr/local/bin/pipedrive-mcp"
    }
  }
}
```

To pin a specific workspace (e.g., when you have several stored), add
`PIPEDRIVE_COMPANY_DOMAIN` under `env` to override the recorded
default for this MCP server only.

## Configuration

Every setting is a `PIPEDRIVE_*` environment variable. The full list, with
defaults and validation rules, is in
[docs/configuration.md](docs/configuration.md). The ones that change what
the server will do at all:

| Env var | Required | Default | Purpose |
| --- | --- | --- | --- |
| `PIPEDRIVE_COMPANY_DOMAIN` | only without `login` | — | Subdomain (e.g. `acme` for `acme.pipedrive.com`). After `pipedrive-mcp login`, recorded in user config and no longer required in env. |
| `PIPEDRIVE_API_TOKEN` | no | — | CI/automation fallback. Prefer `pipedrive-mcp login` for interactive use. |
| `LOG_LEVEL` | no | `info` | `debug` / `info` / `warn` / `error`. |
| `LOG_FORMAT` | no | `text` | `text` / `json`. |
| `PIPEDRIVE_DRY_RUN` | no | `false` | Server-wide dry-run floor: every write becomes a rehearsal. A per-call `dry_run` can only turn one on, never off. |
| `PIPEDRIVE_HTTP_TIMEOUT` | no | `30s` | Per-request outbound HTTP timeout. |

## Tools

Twenty tools. Reads stay discrete and every mutation goes through one
`manage_` tool with an `action`, which is how the Google Workspace MCP
servers shape theirs.

**Start with `search`.** It is the natural-language gateway: it turns a
name into the numeric id every other tool needs. Reaching for `list_deals`
to find "the Acme deal" is the common mistake — it filters, it does not
match names.

| Tool | What it does |
|---|---|
| `search` | Free text across deals, people, organisations, products, files and leads — the way to turn a name into an id |
| `whoami` | Which account the token acts as and which workspace it points at, plus the timezone an activity's due time is written in |
| `get_deal` | One deal: value, currency, status, stage, the people and company on it, and custom fields under their workspace names, dropdowns as labels |
| `list_deals` | Deals by status, pipeline, stage, owner, person, organisation or update window, cursor-paginated. Archived deals live in their own collection — pass `archived` |
| `manage_deal` | Create or edit a deal, move it between stages, close it, archive it, or delete it — `create`, `update`, `move_stage`, `mark_won`, `mark_lost`, `reopen`, `archive`, `unarchive`, `delete`. Custom fields by name, dropdowns by label |
| `get_person` | One contact: names, every email and phone with its label, the company they belong to, and custom fields |
| `list_persons` | People by owner, linked organisation or update window, cursor-paginated |
| `manage_person` | Create, edit or delete a contact — `create`, `update`, `delete`. Custom fields by name, dropdowns by label |
| `get_organization` | One company: the address Pipedrive parsed, how many people hang off it, and custom fields |
| `list_organizations` | Companies by owner or update window, cursor-paginated |
| `manage_organization` | Create, edit or delete a company — `create`, `update`, `delete`. Custom fields by name, dropdowns by label |
| `get_activity` | One call, email, meeting or task, with its location, participants and conference details |
| `list_activities` | Activities by status, owner, deal, person, organisation, lead or update window; notes stripped unless asked for |
| `manage_activity` | Create or edit an activity, tick it off, or delete it — `create`, `update`, `complete`, `reopen`, `delete` |
| `get_note` | One note: its HTML, who wrote it, and which record it hangs off |
| `list_notes` | Notes by the record they hang off, author, date range or update window |
| `manage_note` | Create, edit or remove a note — `create`, `update`, `delete` |
| `list_pipelines` | Every pipeline