mcp-server-pipedrive
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-server-pipedrive
A Model Context Protocol server for Pipedrive CRM. It lets an MCP client (Claude or any other MCP-capable assistant) read deals, persons, organizations, activities, notes, pipelines and users in one Pipedrive company and, when enabled, create and change deals, persons, organizations, activities and notes, and move deals between stages.
This is an independent, unofficial project. It is not developed, endorsed or supported by Pipedrive. It uses only Pipedrive's public API.
Read-only by default; writes are opt-in per instance, and every write can be undone in Pipedrive (a new record, a changed field, a moved deal, an activity marked done). No delete, merge, bulk change, e-mail, invitation, or change to users, permissions, pipelines, stages, fields, filters, products or webhooks, whatever the configuration.
One personal API token per server instance, sent only to
api.pipedrive.comin thex-api-tokenheader; the server does no per-user authorization itself (see Security model).Two transports: stdio for local clients, stateless streamable HTTP for containers and gateways.
Embeddable: the
./gatewayexport exposes the same tools, validation, policy and audit to a host application.
Tools
Tool | Purpose |
| Whether the token works: the user id, the company, its currency and time zone. |
| The company's users (owners of records): id, name, e-mail, active. |
| The pipelines and their stages in order, with win probability. |
| Deals by text, or listed by pipeline, stage, status, owner, person, organization or last change. |
| One deal. |
| Persons by text (name, e-mail, phone), or listed by organization, owner or last change. |
| One person with e-mail addresses and phone numbers. |
| Organizations by text (name, address), or listed by owner or last change. |
| One organization with its address. |
| Activities by deal, person, organization, owner, done or last change. |
| Notes on a deal, person or organization, newest first, as plain text. |
| Create a deal, linked to a person and/or an organization. |
| Change a deal, or mark it won, lost or open again; the answer holds the old values. |
| Move a deal to another stage; the answer holds the stage it was in. |
| Create a person, optionally at an organization. |
| Change a person; the answer holds the old values. |
| Create an organization. |
| Change an organization; the answer holds the old values. |
| Create an activity (call, meeting, task ...) on a deal, person or organization; nothing is sent to anyone. |
| Mark an activity done, move or reassign it; the answer holds the old values. |
| Add a note to a deal, person or organization. |
| Replace a note's text; the answer holds the old text. |
Every read gives on a fixed list of fields per record type (custom fields are left out: their keys mean nothing without the company's field settings); the write tools set only the fields in their input schema. Deals, persons, organizations, activities, pipelines and stages use API v2; notes and users exist only in API v1.
Related MCP server: Pipedrive Universal MCP Server
Access to Pipedrive
The server takes one personal API token: in Pipedrive, the user opens Personal preferences > API (or https://app.pipedrive.com/settings/api) and copies the token. It belongs to that user in that company and carries the user's permissions; there are no scopes to choose. It does not expire, but it stops working when the user generates a new one or leaves the company. A company admin can turn API access off for a permission set, and then the menu is missing.
The token goes in the x-api-token header, as Pipedrive's documentation asks, and only to api.pipedrive.com (Pipedrive finds the company from the token, so no company address is needed).
No OAuth app is used. Under Pipedrive's Developer Agreement, an app distributed commercially is a Marketplace app and needs Pipedrive's approval, even when unlisted; see Sources.
Quick start
Requires Node.js 22 or later and a Pipedrive API token (see Access to Pipedrive). Every Pipedrive plan has the API, the 14-day trial too.
npx mcp-server-pipedriveOr build from source:
git clone https://github.com/borgels/mcp-server-pipedrive.git
cd mcp-server-pipedrive
npm ci
npm run buildClaude Code:
claude mcp add pipedrive \
--env PIPEDRIVE_API_TOKEN=<API token> \
-- npx -y mcp-server-pipedriveClaude Desktop (claude_desktop_config.json), or any client that launches stdio servers:
{
"mcpServers": {
"pipedrive": {
"command": "npx",
"args": ["-y", "mcp-server-pipedrive"],
"env": {
"PIPEDRIVE_API_TOKEN": "<API token>"
}
}
}
}Docker and HTTP
Images are published to ghcr.io/borgels/mcp-server-pipedrive: latest and the commit SHA from main, and vX.Y.Z for release tags. The container serves streamable HTTP at /mcp on port 3000, plus an unauthenticated GET /healthz.
TOKEN=$(openssl rand -hex 32); echo "$TOKEN"
docker run -d --name pipedrive-mcp -p 127.0.0.1:3000:3000 \
-e PIPEDRIVE_API_TOKEN=<API token> \
-e MCP_HTTP_TOKEN="$TOKEN" \
ghcr.io/borgels/mcp-server-pipedrive:latest
claude mcp add --transport http pipedrive http://127.0.0.1:3000/mcp \
--header "Authorization: Bearer $TOKEN"To keep an audit log in the container, mount a writable directory and point PIPEDRIVE_AUDIT_LOG into it (e.g. -v pipedrive-audit:/audit -e PIPEDRIVE_AUDIT_LOG=/audit/audit.jsonl); the image runs as the node user and /app is not writable.
Clients send Authorization: Bearer <MCP_HTTP_TOKEN>. The server will not start on a non-loopback address without a token of at least 32 characters. It does not terminate TLS; run it behind a reverse proxy or gateway that does.
Configuration
Configuration is read from the environment (see .env.example). Invalid numbers, booleans, URLs and unknown tool names stop the server at startup. Booleans accept true/false, 1/0, yes/no and on/off.
Upstream API
Variable | Default | Description |
| – | Required. The personal API token of a Pipedrive user. |
|
| Base URL of the API. Only |
|
| Timeout per request attempt. |
|
| Maximum concurrent upstream requests. |
|
| Largest response body read (at most 100 MB). |
Access control
Variable | Default | Description |
|
| Enable the write tools. |
| – | Comma-separated tool names to disable, with or without the |
| – | Path of a JSONL audit log: one record per tool call start, finish and error, with record ids, internal keys, dates and paging in clear text, no free text or search (not even hashed), duration, status and the caller passed by an embedding host. Write tools refuse to run if the log cannot be written. |
HTTP transport
Variable | Default | Description |
| – | Bearer token, at least 32 printable ASCII characters (also on loopback). Required unless bound to loopback. |
|
| Bind address; |
|
| Listen port. |
| localhost origins | Comma-separated browser origins allowed to call the server. |
|
| Allow any origin; requires a token. |
| loopback names on a loopback bind | Comma-separated accepted |
|
| Maximum request body. |
|
| Failed-authentication limit per client address; |
|
| Permit a non-loopback bind without a token. Only for isolated networks. |
Embedding (./gateway)
A host application can run the tools in-process instead of over MCP:
import { createPipedriveGateway, pipedriveToolCatalog } from 'mcp-server-pipedrive/gateway';
const gateway = createPipedriveGateway({
apiToken: tenant.apiToken,
policy: { enableWrites: true, disabledTools: [] },
});
const result = await gateway.callTool('search_deals', { status: 'won' }, { caller: 'user-1' });Explicit credentials.
apiTokenis required; a missing value throws when the gateway is created. It passes key admission. A gateway never readsPIPEDRIVE_*credentials or addresses from the environment, so one tenant cannot silently fall back to the process's credentials. The stdio and HTTP transports still read them from the environment.Several tenants in one process. Create one gateway per API token. Each instance redacts error text, tool results and audit records with its own key only; no secret is kept in a process-wide registry, and a dropped instance releases its key.
Instance policy from the host. Pass
policytocreatePipedriveGateway:enableWrites(default false),disabledTools(must name known tools) andaudit, a function that receives each audit record instead ofPIPEDRIVE_AUDIT_LOG(without it the instance writes no audit; a write tool does not run if the sink throws on its start record). An instance withpolicyreads none ofPIPEDRIVE_ENABLE_WRITES,PIPEDRIVE_DISABLED_TOOLS, orPIPEDRIVE_AUDIT_LOG, so tenants in one process can have different settings. Withoutpolicythe instance uses the environment, like the MCP server. Each call runs in a scope of its own, so a call made from inside another instance's call never inherits its policy, sink or redactor, and every audit record is redacted as a whole with the instance's own key before the sink sees it. The limits (PIPEDRIVE_TIMEOUT_MS, ...) are still read from the environment and apply to every gateway in the process. Per-user and per-tenant authorization is the host's job.Result format. A successful
callToolresult hasstructuredContentand one text block: a short summary, a blank line, and the same data as compact JSON, as the MCP specification recommends (many clients read only the text). The JSON is built from the redacted result, so it holds exactlystructuredContent. An error result has only its text.Changes for a host log.
resolvePipedriveChange(tool, input)(andgateway.resolveChange) says what a write will change before it is sent: the action, the record and only Pipedrive ids, internal keys (record kind, activity type, deal status, currency code), dates, flags and the names of changed fields, never names, e-mail addresses, amounts or texts. No tool moves money, sorequiresConfirmationis false for all.Tool catalog.
pipedriveToolCatalogis a frozen list of every tool:name(without thepipedrive_prefix),title,description,riskLevel(read,writeordestructive),enabledByDefault,inputSchema(JSON Schema),broad(true when a tool can read more than its name says, so a host gives it only to roles that may read everything) andupstream, the API requests the tool may make (access,methodand path template). It is generated from the same tool table as the MCP server, so it cannot drift from the registered tools.pipedriveGatewayToolsholds the same definitions withoutupstreamandbroad;gateway.toolslists those enabled on the instance.
Threat model
What this server guarantees about the API key, and what it does not. It is the yardstick for every change that touches errors, results or audit.
Scope. Guarantees (a), (b) and (c) apply to the embeddable gateway
(./gateway), the surface a multi-tenant host uses. The standalone MCP
server, configured from the environment for one key, keeps best-effort
redaction: its errors and audit records are redacted with its key, but it is
not held to these guarantees.
Guaranteed:
(a) The key never reaches anything persisted or shared: audit sinks and the audit log file, logs, error texts, export hooks or files. Errors are our own texts; audit records and everything a gateway instance returns are redacted with the instance's own key before they leave it.
(b) No vendor-controlled free text in errors. An error carries our own fixed text, the HTTP status, numbers we parse (Retry-After), and codes from a fixed list we wrote down; never a response body, a vendor message or code, a redirect's
Location, a type or field name from the vendor, or the message of an error thrown while reading a response. A failure kept inside an otherwise returned result is the status or a fixed text as well. Errors never quote the key, the configured address or a refused configuration value (a timeout names its limit in milliseconds).(c) Results go only to the tenant whose key it is. One gateway instance per tenant; every call runs in a scope of its own; nothing about a tenant is kept in process-wide state. The MCP server serves one key.
Not guaranteed (residual risk): a vendor that deliberately echoes the
customer's own key back in data. Results are redacted on a best-effort
basis: the exact key, its URL- and JSON-encoded forms and any piece of it of
6 characters or more, in strings, object keys and the string form of
numbers and booleans, are replaced by "‹redacted›" before anything is
serialised. A key that comes back otherwise transformed (split into pieces
shorter than 6 characters, reversed, re-encoded, hashed) is not recognised.
Such data reaches only the tenant whose key it is, which already holds the
key. What leaves a gateway holds no piece of the key. This is checked at
the sink, not inferred from our texts: every output is checked in its final
form, and one that holds a piece of 6 characters of the key (or of one of
its encoded forms) is replaced by a fixed fallback. The outputs are the tool
list, every tool result as a whole (outer fields such as isError
included), audit records and stderr lines, and construction errors. A result becomes a fixed
"withheld" error, an audit record or line becomes a fixed one, and a
construction error becomes the fixed refusal. Every error a gateway throws is a fresh error in final form: no cause, a stack of only name: message (no frames, paths or function names), and name, message and stack masked against the secret. The fallbacks are a small,
closed set (src/fallbacks.ts), and a key that shares a piece with any of
them, or with the tool list, is refused when the gateway is created.
Key admission. Every key is a secret the vendor issues. A gateway
accepts only printable ASCII (0x21-0x7E) of at least 16 characters, checked
before anything is built from the key. As a cheap first filter it also
refuses a key that shares a piece of 6 characters with a string literal in
src/ (src/fixed-corpus.generated.ts, kept up to date by a test). The
refusal is a fixed text that never repeats the key. The standalone MCP server applies the same redaction to errors
and audit records on a best-effort basis; its successful results are redacted
the same way and withheld whole when a piece of the key remains.
Security model
One shared identity. Every caller acts with the rights of the user whose API token is configured. Writes are limited to the eleven in the tool table.
Per-user authorization belongs in front of the server. The server checks a single bearer token and does not know the end user. For multi-user use, run it behind an identity-aware gateway that decides which users may call which tools, holds the bearer token, and is the only network path to the server. Hosts can also embed the tools through the
./gatewaymodule export and pass the caller identity into the audit log.Tool access is not data access. A gateway controls who may call which tool; every permitted caller still sees everything the API key can see. To separate data, run several instances with different keys.
Writes are off by default. Write tools are annotated as writes (not read-only), and not as destructive: each can be undone in Pipedrive. Clients can still ask for confirmation of every non-read-only tool. Read-only tools get a client that sends only GET. When
PIPEDRIVE_AUDIT_LOGis set, a write tool does not run unless its start record is written; without it there is no audit record.Upstream content is untrusted input. Data returned by the API may be written by anyone with access to it. Tool results label it as data; clients that combine this server with other tools should treat it accordingly.
The API key stays on the API origin. Redirects are never followed, the base URL must use
https, and error messages and audit records are redacted (by each instance, with that instance's key) and size-capped. See the threat model above for what is and is not guaranteed.The HTTP transport fails closed. It refuses to start on a non-loopback address or with any origin allowed unless a token is set, compares tokens in constant time, throttles failed authentication per client address, checks
OriginandHost(DNS rebinding), and caps request bodies.
Report vulnerabilities as described in SECURITY.md.
Sources
Built from Pipedrive's public documentation (read 21.11.2026). The tests use answers shaped as documented; test/live.test.ts runs the tools against a real test company when PIPEDRIVE_TEST_API_TOKEN is set (in CI from the repository secret of that name; without it the job passes with a notice).
API token, header and where to find it: https://pipedrive.readme.io/docs/core-api-concepts-authentication, https://pipedrive.readme.io/docs/how-to-find-the-api-token, https://pipedrive.readme.io/docs/enabling-api-for-company-users.
API v2 and the migration from v1 (v1 deals, persons, organizations, activities, pipelines and stages are out of support from 01.08.2026): https://pipedrive.readme.io/docs/pipedrive-api-v2-migration-guide, https://developers.pipedrive.com/changelog/post/deprecated-apiv1-endpoints-become-out-of-support.
Reference (deals, persons, organizations, activities, pipelines, stages, search, notes, users): https://developers.pipedrive.com/docs/api/v1.
Paging and rate limits: https://pipedrive.readme.io/docs/core-api-concepts-pagination, https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting.
Private apps and the Developer Agreement (private apps for non-commercial use; commercial distribution is a Marketplace app subject to approval): https://pipedrive.readme.io/docs/marketplace-registering-a-private-app, https://www.pipedrive.com/en/developer-agreement.
Development
npm run dev # stdio transport
npm run dev:http # HTTP transport on 127.0.0.1:3000
npm run typecheck
npm test
npm run buildProject layout:
Path | Contents |
| Shared tool table (MCP and gateway), policy and audit wrapper. |
| The API calls and the schemas each answer is parsed with. |
| Upstream client, API calls, policy, audit, tool annotations. |
| stdio and HTTP entry points; HTTP auth, origin and host checks. |
| Embeddable entry point ( |
| Validated environment readers. |
Releasing
Bump the version in
package.json,server.json(versionand the npm packageversion) andsrc/version.ts; tests and CI check that they agree. UpdateCHANGELOG.md. Merge.Tag the merged commit and push the tag:
git tag vX.Y.Z && git push origin vX.Y.Z.release.ymltests, packs and publishes the tarball to npm through trusted publishing (no stored token; npm adds provenance when the repository is public), then publishesserver.jsonto the MCP Registry. Versions already on npm or in the registry are skipped, so a failed run can be re-run. Pre-release tags (vX.Y.Z-rc.1) go to the npm dist-tagnextand not to the registry.publish.ymlpushes thevX.Y.Zimage.
The first version of a new package is published by hand; see the header of .github/workflows/release.yml (and docs/NEW-SERVER.md).
License
Apache-2.0
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
CRM1Unofficial Pipedrive MCP Pack — wraps the Pipedrive REST API v1
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Read native sales pipelines, customer-learning records and recorded sales evidence in your connected workspace. Native pipeline and learning reads use Contacts read (crm:read). Recorded costs and outcomes also require Operations read and Accounting read; communication-source readouts require Communications read. The separate Sales read (sales:read) permission covers eligible legacy chauffeur inquiry and offer adapters and is not required for the native pipeline. Setup: In a remote MCP client supporting Streamable HTTP and OAuth, add https://platform.samuelz.com/api/v1/mcp/operator?toolset=sales. Sign in and select your authorized workspace. For read-only review, select only the read permissions needed for the tools above. Current membership and module permissions are checked on every call. Write tools require separate authorization and retain their native approval rules. Reading never sends messages, books services or collects payments.
Related MCP Servers
- AlicenseCqualityBmaintenanceMCP server for Pipedrive CRM providing 88 tools for full CRUD on deals, persons, organizations, activities, and more, with custom field resolution and safety guards.938MIT
- AlicenseNot gradedqualityDmaintenanceUniversal MCP server for Pipedrive, enabling interaction with Pipedrive's tools and services through a standardized API.1MIT
- AlicenseNot gradedqualityCmaintenanceWraps the Pipedrive REST API v1 to manage deals, contacts, and search across CRM entities via MCP tools.81 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables reading and managing Pipedrive CRM records—deals, people, organizations, activities, and notes—over MCP, including searching, writing, and moving deals through pipelines.Apache 2.0