luisra51/mcp-pipedrive repository overview

⁠mcp-pipedrive

MCP server exposing the Pipedrive CRM API as Model Context Protocol tools. v2-first with v1 fallback, dual authentication (API token or OAuth), write/delete guardrails, optional bbolt-backed cache.

⁠Transports

• stdio (default) — Claude Desktop, Codex CLI, local subprocesses
• sse — HTTP Server-Sent Events
• streamable-http — modern HTTP streaming (recommended for remote)

⁠Authentication

Set exactly one of:

When both are set, OAuth wins.

Set PIPEDRIVE_DOMAIN to your Pipedrive subdomain, e.g. mycompany.pipedrive.com. For OAuth-scoped access use api.pipedrive.com (default).

⁠Configuration

⁠Cache

⁠HTTP header overrides (SSE / streamable-http)

⁠Tools (69 total)

⁠Read

• pipedrive.context.get — users, pipelines, stages, deal-fields, activity-types (cached)
• pipedrive.filters.list — discover saved filters; pass the returned id as filter_id on any list tool to reproduce a Pipedrive UI view. See docs/filters.md⁠.
• pipedrive.webhooks.list — webhook subscriptions
• pipedrive.deals.{list,get,search}
• pipedrive.deals.products.list
• pipedrive.persons.{list,get,search}
• pipedrive.organizations.{list,get,search}
• pipedrive.products.{list,get,search}
• pipedrive.leads.{list,get,search}
• pipedrive.activities.{list,get}
• pipedrive.notes.list
• pipedrive.deals.followers.list
• pipedrive.persons.followers.list
• pipedrive.organizations.followers.list
• pipedrive.mail.threads.{list,get} — token owner's connected mailbox (single-user scope). list supports since, unread_only, fields=compact|full.
• pipedrive.mail.messages.get — one message with body. body_format=text|html|none. Cross-user scope.
• pipedrive.deals.mail.list — all mail tied to a deal across the workspace (cross-user; aggregates teammates' mail). Body backfill is bounded-concurrency and reuses the cache.
• pipedrive.cache.stats

⁠Write (gated by PIPEDRIVE_ALLOW_WRITE=true)

• pipedrive.deals.{create,update}
• pipedrive.deals.{archive,unarchive} — sets is_archived via PATCH
• pipedrive.deal_fields.add_option — append options to enum/set deal fields
• pipedrive.deals.products.{attach,update,detach}
• pipedrive.persons.{create,update}
• pipedrive.organizations.{create,update}
• pipedrive.products.{create,update}
• pipedrive.filters.{create,update} — saved filters for server-side (incl. custom-field) filtering
• pipedrive.leads.{create,update}
• pipedrive.activities.{create,update,batch_create} — batch_create supports up to 100 activities per call
• pipedrive.notes.{create,update} — both accept user_id to set the note author (e.g. the deal owner); Pipedrive only lets admin tokens change it
• pipedrive.webhooks.create — Pipedrive POSTs matching events to subscription_url
• pipedrive.deals.followers.{add,remove}
• pipedrive.persons.followers.{add,remove}
• pipedrive.organizations.followers.{add,remove}

⁠Delete (gated by PIPEDRIVE_ALLOW_WRITE=true AND PIPEDRIVE_ALLOW_DELETE=true)

Delete tools require both flags — PIPEDRIVE_ALLOW_DELETE=true alone is not sufficient.

• pipedrive.deals.delete
• pipedrive.persons.delete
• pipedrive.organizations.delete
• pipedrive.products.delete
• pipedrive.leads.delete
• pipedrive.activities.delete
• pipedrive.webhooks.delete

⁠Admin (gated by PIPEDRIVE_ENABLE_ADMIN_TOOLS=true)

• pipedrive.cache.clear
• pipedrive.cache.invalidate

All write/delete tools are registered regardless of flag state; when disabled they return a structured error {"error":"write_disabled"|"delete_disabled"|"admin_tools_disabled", "message":"..."} so callers can detect capability without trial-and-error.

⁠Role-based configurations (token savings)

Every tools/list call ships the full schema of every registered tool into the LLM's context. The allowlist (PIPEDRIVE_ALLOWED_TOOLS) filters at registration time, so unlisted tools don't appear in tools/list at all — the token cost drops proportionally.

Measured with cl100k_base (OpenAI tokenizer). Claude's tokenizer is typically within ±10 %.

Token figures were measured against the pre-68-tool catalog; treat them as lower bounds until re-measured.

Each role file contains a ready-to-paste PIPEDRIVE_ALLOWED_TOOLS value plus the right ALLOW_WRITE / ALLOW_DELETE / ENABLE_ADMIN_TOOLS flags. Start at docs/roles.md⁠ for the index, Pipedrive permission-set mapping, and guidance on picking the right profile.

⁠Cache modes

Every read tool accepts an optional cache_mode:

Every response carries a meta.cache block:

{
  "cache": {
    "hit": true,
    "stale": false,
    "stored_at": "2026-04-16T10:30:00Z",
    "expires_at": "2026-04-16T10:35:00Z",
    "ttl_seconds": 300
  }
}

⁠Running

⁠Docker

docker run -i --rm \
  -e PIPEDRIVE_API_TOKEN=xxx \
  -e PIPEDRIVE_DOMAIN=mycompany.pipedrive.com \
  luisra51/mcp-pipedrive:latest -t stdio

⁠Local

PIPEDRIVE_API_TOKEN=xxx PIPEDRIVE_DOMAIN=mycompany.pipedrive.com \
  go run ./cmd/mcp-pipedrive -t stdio

⁠Development

task dev:up                                 # start dev container
task dev:exec CMD='go build ./...'          # build
task dev:exec CMD='go test ./...'           # test
task dev:exec CMD='go run ./cmd/mcp-pipedrive -t stdio'
task dev:down                               # stop

⁠Release

Tag a semver commit to trigger the Docker Hub build (luisra51/mcp-pipedrive):

git tag v0.1.0
git push origin v0.1.0

⁠License

MIT.