Skip to main content
Glama
Sign In
nubiia-dev

Pipedrive MCP Server

by nubiia-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

deals_list

Lists Pipedrive deals page by page with cursor pagination and filters for status, stage, owner, person, organization, pipeline, or creation date.

Instructions

List deals with cursor-based pagination and filtering options. Backed by Pipedrive API v2 (GET /api/v2/deals).

Returns a page of deals. Use filters to narrow results by status, stage, owner, person, organization, or pipeline.

Workflow tips:

  • Use status filter to get only 'open', 'won', 'lost', or 'deleted' deals; omit status entirely for all non-deleted deals (v1's 'all_not_deleted' has no v2 equivalent, so it is dropped rather than sent)

  • Set owned_by_you=1 to see only your deals (resolves your user id via GET /users/me, cached)

  • Combine with filter_id to use pre-configured Pipedrive filters

  • Paginate with cursor: pass the cursor from the previous response's additional_data.next_cursor to get the next page; omit it (or pass null) for the first page. A null next_cursor means you're on the last page. 'start' is deprecated and ignored — v2 does not support offset pagination.

  • sort_by only accepts a small set of v2 fields (confirmed working: id, add_time, update_time) — arbitrary v1 sort fields like 'title' or 'value' will be rejected by the API

  • For all deals without manual pagination, use deals/list_all_auto instead

  • Use add_time_from / add_time_until to filter by creation date (client-side). NOTE: this only filters the current page; for complete date-range results use deals/list_all_auto

Common use cases:

  • List all open deals: { "status": "open" }

  • List my won deals: { "status": "won", "owned_by_you": 1 }

  • List deals in a specific stage: { "stage_id": 123 }

  • Get the next page: { "cursor": "<next_cursor from previous response>" }

Input Schema

NameRequiredDescriptionDefault
sortNoField to sort by. v2 only accepts a small enum — confirmed working: id, add_time, update_time.
limitNoNumber of items to return
startNoDEPRECATED — ignored. v2 uses cursor-based pagination; see "cursor".
cursorNoOpaque cursor from a previous response (additional_data.next_cursor) to fetch the next page.
org_idNoFilter by organization ID
statusNoFilter by deal status. 'all_not_deleted' is v1-only and is translated to 'no status filter' since v2 has no such value.
sort_byNoSort direction
user_idNoFilter by user (owner) ID — sent as owner_id to v2. If owned_by_you=1 is also set, owned_by_you takes precedence and this value is ignored.
stage_idNoFilter by stage ID
filter_idNoID of the filter to use
person_idNoFilter by person ID
pipeline_idNoFilter by pipeline ID
owned_by_youNoFilter deals owned by the authorized user (1 = yes, 0 = no). Takes precedence over user_id when both are provided.
add_time_fromNoFilter deals created on or after this date (YYYY-MM-DD). Applied client-side.
add_time_untilNoFilter deals created on or before this date (YYYY-MM-DD). Applied client-side.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv2.7.1
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "Opaque cursor from a previous response (additional_data.next_cursor) to fetch the next page.",
+  "type": "string"
+}
    • changedInput schema / properties / owned_by_you / description
      Previous value: -"Filter deals owned by the authorized user (1 = yes, 0 = no)"New value: +"Filter deals owned by the authorized user (1 = yes, 0 = no). Takes precedence over user_id when both are provided."
    • changedInput schema / properties / sort / description
      Previous value: -"Field to sort by (e.g., title, value, stage_id)"New value: +"Field to sort by. v2 only accepts a small enum — confirmed working: id, add_time, update_time."
    • changedInput schema / properties / start / description
      Previous value: -"Pagination start"New value: +"DEPRECATED — ignored. v2 uses cursor-based pagination; see \"cursor\"."
    • changedInput schema / properties / status / description
      Previous value: -"Filter by deal status"New value: +"Filter by deal status. 'all_not_deleted' is v1-only and is translated to 'no status filter' since v2 has no such value."
    • changedInput schema / properties / user_id / description
      Previous value: -"Filter by user (owner) ID"New value: +"Filter by user (owner) ID — sent as owner_id to v2. If owned_by_you=1 is also set, owned_by_you takes precedence and this value is ignored."
  2. Changed2 schema fields changedv2.3.1
    • addedInput schema / properties / add_time_from
      Added value: +{
+  "description": "Filter deals created on or after this date (YYYY-MM-DD). Applied client-side.",
+  "type": "string"
+}
    • addedInput schema / properties / add_time_until
      Added value: +{
+  "description": "Filter deals created on or before this date (YYYY-MM-DD). Applied client-side.",
+  "type": "string"
+}
  3. First observedv2.1.0

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure and does much of it: cursor round-trip semantics, null next_cursor meaning last page, deprecated 'start' being ignored, sort_by field rejection by the API, client-side-only date filtering, and cached /users/me resolution for owned_by_you. It omits permissions/scope requirements and any rate-limit or page-size constraints, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return behavior, then organized into bulleted workflow tips and use cases that each carry distinct information. Some redundancy exists (sort_by restriction is restated from the schema, and the common use cases overlap the tips), so it is efficient but not maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter, no-output-schema read tool, the description covers return shape (a page plus additional_data.next_cursor), pagination termination, filter precedence, and the alternative bulk tool. Nothing critical to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'start' is confirmed ignored, sort_by accepts only id/add_time/update_time, status 'all_not_deleted' is dropped rather than sent, owned_by_you overrides user_id, and cursor must come from additional_data.next_cursor. These are semantics an agent needs that the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List deals') plus the mechanism ('cursor-based pagination and filtering') and the backing endpoint (GET /api/v2/deals). Distinguishes itself implicitly from deals_list_archived and explicitly from deals/list_all_auto, so an agent can separate it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when/when-not guidance: use deals/list_all_auto when you don't want manual pagination, use add_time filters only for per-page narrowing, omit status for all non-deleted deals. Concrete invocation examples ('List my won deals': status=won, owned_by_you=1) further reduce ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools