Pipedrive MCP Server

A single-tenant, self-hosted Model Context Protocol server for Pipedrive. Version 2.x uses Pipedrive API v2 for deals, persons, organizations, pipelines, stages, leads, and item search. Notes and users remain isolated behind clearly scoped v1 adapters because Pipedrive has not moved those APIs to v2.

The server is read-only by default. Two narrowly scoped write tools can be enabled explicitly and remain preview-first.

Requirements

• Node.js 22 or 24 (Node 24 recommended)
• A Pipedrive API token

PIPEDRIVE_DOMAIN is not used. The official Pipedrive client supplies the API base URL.

Install and run with stdio

Install globally:

npm install --global pipedrive-mcp-server
PIPEDRIVE_API_TOKEN=your-token pipedrive-mcp-server

Or build this repository:

npm ci
npm run check
PIPEDRIVE_API_TOKEN=your-token npm start

Example desktop MCP configuration:

{
  "mcpServers": {
    "pipedrive": {
      "command": "pipedrive-mcp-server",
      "env": {
        "PIPEDRIVE_API_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP

The modern HTTP endpoint defaults to http://127.0.0.1:3000/mcp:

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
pipedrive-mcp-server

GET /health is unauthenticated, host-validated, and returns only service status. The server creates an independent MCP server and transport for every session and closes active sessions during shutdown.

Binding to a non-loopback address requires both an HS256 JWT secret of at least 32 characters and an explicit hostname allowlist:

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=mcp.example.com \
MCP_ALLOWED_ORIGINS=https://app.example.com \
MCP_JWT_SECRET='replace-with-at-least-32-random-characters' \
pipedrive-mcp-server

The built-in HTTP server does not terminate TLS. Never expose it directly on an untrusted network: place it behind a trusted HTTPS reverse proxy, keep the application port private, and configure the proxy to replace (not append to) forwarding headers. JWT bearer tokens are replayable if captured. Docker Compose therefore publishes the service only on host loopback by default; remote operators must add a TLS terminator before changing that binding.

Clients send Authorization: Bearer <token>. Tokens must use HS256. MCP_JWT_ISSUER and MCP_JWT_AUDIENCE add optional claim validation. There is no boot-token setting.

MCP_ALLOWED_ORIGINS is an exact, comma-separated allowlist. When it is empty the server emits no CORS headers; wildcard CORS is not supported. MCP_ALLOWED_HOSTS contains hostnames only, without schemes, paths, or ports.

Legacy SSE

The deprecated compatibility routes are GET /sse and POST /messages. They are enabled by default in 2.x and can be disabled with MCP_ENABLE_LEGACY_SSE=false. MCP_TRANSPORT=sse remains an alias for HTTP mode and emits a warning. These routes are planned for removal in 3.0.

Docker

Copy .env.example to .env, set PIPEDRIVE_API_TOKEN, and set a random MCP_JWT_SECRET of at least 32 characters. Then run:

docker compose up --build -d
docker compose ps

Compose serves /mcp on port 3000, requires JWT for MCP routes, runs as the unprivileged node user, and checks /health with Node’s built-in fetch. Published images use ghcr.io/willdent/pipedrive-mcp-server.

For stdio in Docker, override the transport and disable the HTTP health check: