Pipedrive MCP

pipedrive-mcp

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 over stdio, from the current protocol revision back to 2024-11-05. It runs as a subprocess of your client, on your own machine, against one Pipedrive workspace, with your own API token. There is no server to host and no shared deployment.

It is for a person who works in Pipedrive and wants an assistant to do that work with them: turn a name into a record, read deals, people, organizations, activities and notes with their custom fields under the names the workspace gives them, edit any of them, and move a deal through its pipeline: won, lost, reopened, archived or into another stage.

Unofficial. Not affiliated with or endorsed by Pipedrive.

Goals and non-goals

Goals:

• Nothing is overwritten that you did not mean to replace. A write to an existing record reads it first, and refuses to replace a field that holds a value unless the call names that field. Pipedrive has no undo.
• A refusal says how to proceed. It names what it protects and the argument that would permit the write.
• Results speak the workspace's language. Custom fields come back under their names and dropdowns as their labels, and are written the same way.
• Your workspace stays yours. Every call runs with your token, only to your workspace's Pipedrive address, with no telemetry. Logs never carry a payload or the token.

Non-goals:

• More than one workspace per server. It resolves one at startup.
• Clearing a field. Pipedrive v2 rejects a null and stores an empty string as a value, so a field can be changed but not emptied.
• Merging records. A merge destroys one record's values across a record nobody read, and no refusal could name what it would lose.
• Products, leads, files, projects and goals. search finds some of them, and no tool reads or writes them.
• Fetching every page for you. Each list call returns one page and the cursor for the next.
• Asking you before a call. Your client approves each call; the server asks nothing.

What makes this one different

It stays on Pipedrive v2, except where v2 has nothing. Notes and the whoami lookup run on API v1, because v2 exposes no /notes and no /users. Pipedrive has deprecated a list of v1 endpoints, and notes and /users/me are not on it. If v1 answers one of them with a 410, the [gone] error says the endpoint has no v2 equivalent, rather than blaming your request. Any other answer is classified by its status.

Its tool surface follows the shipped Google Workspace MCP servers. 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 this one needs less explaining.

It is checked against a real workspace. Beside the unit tests, a suite in internal/integration drives the server against a live Pipedrive workspace: reads, resources, guard refusals, rehearsals, and a reversible write on each resource that has one. Writing to a live CRM is a separate opt-in, and the suite has run against one workspace, so a custom-field or permission setup unlike it is untested.

Tools

Start with `search`. It turns a name into the numeric id every other tool needs. list_deals filters; it does not match names.

Guarded writes

Every manage_ tool reads its target before it writes, and refuses what the write would destroy that you cannot see. Each refusal names the fields it is protecting and the argument that would permit the write.

• `dry_run` reports what the write would find and change, and sends nothing.
• `overwrite` names the fields an update may replace, such as ["title", "value"], exactly as the refusal lists them. Naming fewer than it listed is still refused over the rest. Filling an empty field destroys nothing and needs no permission.
• `expect_version` carries the update_time from the read that informed the write, and refuses if the record moved since. Pipedrive has no compare-and-set, so it catches a concurrent edit, not a determined race.

The named transitions — mark_won, mark_lost, move_stage, reopen, archive, unarchive and complete — take no overwrite, because the field they change is the field you named. reopen undoes mark_won and mark_lost on a deal, and complete on an activity. It does not clear a deal's lost_reason: Pipedrive accepts that field only on a lost deal, so the last loss's text stays until the deal is lost again.

A delete is soft. Pipedrive removes a deleted deal, person, organization or activity for good after 30 days, and nothing here puts one back. A deleted note keeps its text, and nothing here restores it either.

A guarded write that stops returns [refused], a class of its own, so a model can tell it from a validation failure and from an upstream error.

Resources

Resource templates mirror the get_ tools for clients that attach records rather than calling tools:

pipedrive://deals/{id}          pipedrive://organizations/{id}

pipedrive://persons/{id} pipedrive://activities/{id} pipedrive://notes/{id}

They share the tools' code, so the two cannot describe a record differently. A URI carries no options, so include_attendees and include_notes still need the tool.

What is not here

Each of these is a decision or an API limit, not an oversight.

• Resources not modeled at all: webhooks, mail and mail threads, subscriptions and recurring revenue, saved filters, currencies, deal-to-lead conversion, followers, deal participants as a managed relation, and custom field definitions. Custom field values are readable and writable; the definitions are not.
• Two things the API cannot do, which no retry fixes. Activity type cannot be filtered server-side, so ask for the rows and filter on their type. Activities are not indexed by search, so reach them through list_activities.
• Pipedrive's search index keeps deleted records, with nothing saying so. search checks organization and person hits against Pipedrive and drops the deleted ones, at one extra call per type a page holds. Deals are not checked, because Pipedrive drops deleted deals itself, and a check against /deals would drop archived ones. Products, files and leads are returned unchecked. Because the drop happens after Pipedrive has paged, a page can come back short, or empty with next_cursor still set: an empty page is not the end.
• The v1 tools sit outside the compatibility promise. get_note, list_notes, manage_note and whoami leave in a minor release if v1 stops answering them; see CHANGELOG.md.

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, 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, for Linux, macOS or Windows on amd64 or arm64, and put the binary on your PATH. Verify it first:

# One keyless signature over the checksum file, tied to the release

workflow on a tag. Until it passes, the checksums are only what the

release says.

cosign verify-blob checksums.txt \ --bundle checksums.txt.bundle \ --certificate-identity-regexp '^https://github\.com/mmedum/pipedrive-mcp/\.github/workflows/release\.yml@refs/tags/' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

checksums.txt covers every archive and SBOM, and you downloaded one.

On macOS, use shasum -a 256 -c.

sha256sum -c checksums.txt --ignore-missing

The archive carries build provenance.

gh attestation verify pipedrive-mcp_X.Y.Z_linux_amd64.tar.gz --owner mmedum

Set up Pipedrive

The server keeps your API token in the OS keyring: libsecret on Linux, Keychain on macOS, Credential Manager on Windows. Store it once:

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. login checks the token with Pipedrive before it stores anything, and records th