Pipedrive Automation

1---
2name: pipedrive-automation
3description: "Automate Pipedrive CRM operations including deals, contacts, organizations, activities, notes, and pipeline management via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Pipedrive Automation via Rube MCP
9 
10Automate Pipedrive CRM workflows including deal management, contact and organization operations, activity scheduling, notes, and pipeline/stage queries through Composio's Pipedrive toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Pipedrive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `pipedrive`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `pipedrive`
253. If connection is not ACTIVE, follow the returned auth link to complete Pipedrive OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Create and Manage Deals
31 
32**When to use**: User wants to create a new deal, update an existing deal, or review deal details in the sales pipeline.
33 
34**Tool sequence**:
351. `PIPEDRIVE_SEARCH_ORGANIZATIONS` - Find existing org to link to the deal [Optional]
362. `PIPEDRIVE_ADD_AN_ORGANIZATION` - Create organization if none found [Optional]
373. `PIPEDRIVE_SEARCH_PERSONS` - Find existing contact to link [Optional]
384. `PIPEDRIVE_ADD_A_PERSON` - Create contact if none found [Optional]
395. `PIPEDRIVE_GET_ALL_PIPELINES` - Resolve pipeline ID [Prerequisite]
406. `PIPEDRIVE_GET_ALL_STAGES` - Resolve stage ID within the pipeline [Prerequisite]
417. `PIPEDRIVE_ADD_A_DEAL` - Create the deal with title, value, org_id, person_id, stage_id [Required]
428. `PIPEDRIVE_UPDATE_A_DEAL` - Modify deal properties after creation [Optional]
439. `PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL` - Attach line items/products [Optional]
44 
45**Key parameters**:
46- `title`: Deal title (required for creation)
47- `value`: Monetary value of the deal
48- `currency`: 3-letter ISO currency code (e.g., "USD")
49- `pipeline_id` / `stage_id`: Numeric IDs for pipeline placement
50- `org_id` / `person_id`: Link to organization and contact
51- `status`: "open", "won", or "lost"
52- `expected_close_date`: Format YYYY-MM-DD
53 
54**Pitfalls**:
55- `title` is the only required field for `PIPEDRIVE_ADD_A_DEAL`; all others are optional
56- Custom fields appear as long hash keys in responses; use dealFields endpoint to map them
57- `PIPEDRIVE_UPDATE_A_DEAL` requires the numeric `id` of the deal
58- Setting `status` to "lost" requires also providing `lost_reason`
59 
60### 2. Manage Contacts (Persons and Organizations)
61 
62**When to use**: User wants to create, update, search, or list contacts and companies in Pipedrive.
63 
64**Tool sequence**:
651. `PIPEDRIVE_SEARCH_PERSONS` - Search for existing person by name, email, or phone [Prerequisite]
662. `PIPEDRIVE_ADD_A_PERSON` - Create new contact if not found [Required]
673. `PIPEDRIVE_UPDATE_A_PERSON` - Modify existing contact details [Optional]
684. `PIPEDRIVE_GET_DETAILS_OF_A_PERSON` - Retrieve full contact record [Optional]
695. `PIPEDRIVE_SEARCH_ORGANIZATIONS` - Search for existing organization [Prerequisite]
706. `PIPEDRIVE_ADD_AN_ORGANIZATION` - Create new organization if not found [Required]
717. `PIPEDRIVE_UPDATE_AN_ORGANIZATION` - Modify organization properties [Optional]
728. `PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION` - Retrieve full org record [Optional]
73 
74**Key parameters**:
75- `name`: Required for both person and organization creation
76- `email`: Array of objects with `value`, `label`, `primary` fields for persons
77- `phone`: Array of objects with `value`, `label`, `primary` fields for persons
78- `org_id`: Link a person to an organization
79- `visible_to`: 1 = owner only, 3 = entire company
80- `term`: Search term for SEARCH_PERSONS / SEARCH_ORGANIZATIONS (minimum 2 characters)
81 
82**Pitfalls**:
83- `PIPEDRIVE_ADD_AN_ORGANIZATION` may auto-merge with an existing org; check `response.additional_data.didMerge`
84- Email and phone fields are arrays of objects, not plain strings: `[{"value": "test@example.com", "label": "work", "primary": true}]`
85- `PIPEDRIVE_SEARCH_PERSONS` wildcards like `*` or `@` are NOT supported; use `PIPEDRIVE_GET_ALL_PERSONS` to list all
86- Deletion via `PIPEDRIVE_DELETE_A_PERSON` or `PIPEDRIVE_DELETE_AN_ORGANIZATION` is soft-delete with 30-day retention, then permanent
87 
88### 3. Schedule and Track Activities
89 
90**When to use**: User wants to create calls, meetings, tasks, or other activities linked to deals, contacts, or organizations.
91 
92**Tool sequence**:
931. `PIPEDRIVE_SEARCH_PERSONS` or `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` - Resolve linked entity IDs [Prerequisite]
942. `PIPEDRIVE_ADD_AN_ACTIVITY` - Create the activity with subject, type, due date [Required]
953. `PIPEDRIVE_UPDATE_AN_ACTIVITY` - Modify activity details or mark as done [Optional]
964. `PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY` - Retrieve activity record [Optional]
975. `PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER` - List user's activities [Optional]
98 
99**Key parameters**:
100- `subject`: Activity title (required)
101- `type`: Activity type key string, e.g., "call", "meeting", "task", "email" (required)
102- `due_date`: Format YYYY-MM-DD
103- `due_time`: Format HH:MM
104- `duration`: Format HH:MM (e.g., "00:30" for 30 minutes)
105- `deal_id` / `person_id` / `org_id`: Link to related entities
106- `done`: 0 = not done, 1 = done
107 
108**Pitfalls**:
109- Both `subject` and `type` are required for `PIPEDRIVE_ADD_AN_ACTIVITY`
110- `type` must match an existing ActivityTypes key_string in the account
111- `done` is an integer (0 or 1), not a boolean
112- Response includes `more_activities_scheduled_in_context` in additional_data
113 
114### 4. Add and Manage Notes
115 
116**When to use**: User wants to attach notes to deals, persons, organizations, leads, or projects.
117 
118**Tool sequence**:
1191. `PIPEDRIVE_SEARCH_PERSONS` or `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` - Resolve entity ID [Prerequisite]
1202. `PIPEDRIVE_ADD_A_NOTE` - Create note with HTML content linked to an entity [Required]
1213. `PIPEDRIVE_UPDATE_A_NOTE` - Modify note content [Optional]
1224. `PIPEDRIVE_GET_ALL_NOTES` - List notes filtered by entity [Optional]
1235. `PIPEDRIVE_GET_ALL_COMMENTS_FOR_A_NOTE` - Retrieve comments on a note [Optional]
124 
125**Key parameters**:
126- `content`: Note body in HTML format (required)
127- `deal_id` / `person_id` / `org_id` / `lead_id` / `project_id`: At least one entity link required
128- `pinned_to_deal_flag` / `pinned_to_person_flag`: Filter pinned notes when listing
129 
130**Pitfalls**:
131- `content` is required and supports HTML; plain text works but is sanitized server-side
132- At least one of `deal_id`, `person_id`, `org_id`, `lead_id`, or `project_id` must be provided
133- `PIPEDRIVE_GET_ALL_NOTES` returns notes across all entities by default; filter with entity ID params
134 
135### 5. Query Pipelines and Stages
136 
137**When to use**: User wants to view sales pipelines, stages, or deals within a pipeline/stage.
138 
139**Tool sequence**:
1401. `PIPEDRIVE_GET_ALL_PIPELINES` - List all pipelines and their IDs [Required]
1412. `PIPEDRIVE_GET_ONE_PIPELINE` - Get details and deal summary for a specific pipeline [Optional]
1423. `PIPEDRIVE_GET_ALL_STAGES` - List all stages, optionally filtered by pipeline [Required]
1434. `PIPEDRIVE_GET_ONE_STAGE` - Get details for a specific stage [Optional]
1445. `PIPEDRIVE_GET_DEALS_IN_A_PIPELINE` - List all deals across stages in a pipeline [Optional]
1456. `PIPEDRIVE_GET_DEALS_IN_A_STAGE` - List deals in a specific stage [Optional]
146 
147**Key parameters**:
148- `id`: Pipeline or stage ID (required for single-item endpoints)
149- `pipeline_id`: Filter stages by pipeline
150- `totals_convert_currency`: 3-letter currency code or "default_currency" for converted totals
151- `get_summary`: Set to 1 for deal summary in pipeline responses
152 
153**Pitfalls**:
154- `PIPEDRIVE_GET_ALL_PIPELINES` takes no parameters; returns all pipelines
155- `PIPEDRIVE_GET_ALL_STAGES` returns stages for ALL pipelines unless `pipeline_id` is specified
156- Deal counts in pipeline summaries use `per_stages_converted` only when `totals_convert_currency` is set
157 
158## Common Patterns
159 
160### ID Resolution
161Always resolve display names to numeric IDs before operations:
162- **Organization name -> org_id**: `PIPEDRIVE_SEARCH_ORGANIZATIONS` with `term` param
163- **Person name -> person_id**: `PIPEDRIVE_SEARCH_PERSONS` with `term` param
164- **Pipeline name -> pipeline_id**: `PIPEDRIVE_GET_ALL_PIPELINES` then match by name
165- **Stage name -> stage_id**: `PIPEDRIVE_GET_ALL_STAGES` with `pipeline_id` then match by name
166 
167### Pagination
168Most list endpoints use offset-based pagination:
169- Use `start` (offset) and `limit` (page size) parameters
170- Check `additional_data.pagination.more_items_in_collection` to know if more pages exist
171- Use `additional_data.pagination.next_start` as the `start` value for the next page
172- Default limit is ~500 for some endpoints; set explicitly for predictable paging
173 
174## Known Pitfalls
175 
176### ID Formats
177- All entity IDs (deal, person, org, activity, pipeline, stage) are numeric integers
178- Lead IDs are UUID strings, not integers
179- Custom field keys are long alphanumeric hashes (e.g., "a1b2c3d4e5f6...")
180 
181### Rate Limits
182- Pipedrive enforces per-company API rate limits; bulk operations should be paced
183- `PIPEDRIVE_GET_ALL_PERSONS` and `PIPEDRIVE_GET_ALL_ORGANIZATIONS` can return large datasets; always paginate
184 
185### Parameter Quirks
186- Email and phone on persons are arrays of objects, not plain strings
187- `visible_to` is numeric: 1 = owner only, 3 = entire company, 5 = specific groups
188- `done` on activities is integer 0/1, not boolean true/false
189- Organization creation may auto-merge duplicates silently; check `didMerge` in response
190- `PIPEDRIVE_SEARCH_PERSONS` requires minimum 2 characters and does not support wildcards
191 
192### Response Structure
193- Custom fields appear as hash keys in responses; map them via the respective Fields endpoints
194- Responses often nest data under `response.data.data` in wrapped executions
195- Search results are under `response.data.items`, not top-level
196 
197## Quick Reference
198 
199| Task | Tool Slug | Key Params |
200|------|-----------|------------|
201| Create deal | `PIPEDRIVE_ADD_A_DEAL` | `title`, `value`, `org_id`, `stage_id` |
202| Update deal | `PIPEDRIVE_UPDATE_A_DEAL` | `id`, `status`, `value`, `stage_id` |
203| Get deal details | `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` | `id` |
204| Search persons | `PIPEDRIVE_SEARCH_PERSONS` | `term`, `fields` |
205| Add person | `PIPEDRIVE_ADD_A_PERSON` | `name`, `email`, `phone`, `org_id` |
206| Update person | `PIPEDRIVE_UPDATE_A_PERSON` | `id`, `name`, `email` |
207| Get person details | `PIPEDRIVE_GET_DETAILS_OF_A_PERSON` | `id` |
208| List all persons | `PIPEDRIVE_GET_ALL_PERSONS` | `start`, `limit`, `filter_id` |
209| Search organizations | `PIPEDRIVE_SEARCH_ORGANIZATIONS` | `term`, `fields` |
210| Add organization | `PIPEDRIVE_ADD_AN_ORGANIZATION` | `name`, `visible_to` |
211| Update organization | `PIPEDRIVE_UPDATE_AN_ORGANIZATION` | `id`, `name`, `address` |
212| Get org details | `PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION` | `id` |
213| Add activity | `PIPEDRIVE_ADD_AN_ACTIVITY` | `subject`, `type`, `due_date`, `deal_id` |
214| Update activity | `PIPEDRIVE_UPDATE_AN_ACTIVITY` | `id`, `done`, `due_date` |
215| Get activity details | `PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY` | `id` |
216| List user activities | `PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER` | `user_id`, `start`, `limit` |
217| Add note | `PIPEDRIVE_ADD_A_NOTE` | `content`, `deal_id` or `person_id` |
218| List notes | `PIPEDRIVE_GET_ALL_NOTES` | `deal_id`, `person_id`, `start`, `limit` |
219| List pipelines | `PIPEDRIVE_GET_ALL_PIPELINES` | (none) |
220| Get pipeline details | `PIPEDRIVE_GET_ONE_PIPELINE` | `id` |
221| List stages | `PIPEDRIVE_GET_ALL_STAGES` | `pipeline_id` |
222| Deals in pipeline | `PIPEDRIVE_GET_DEALS_IN_A_PIPELINE` | `id`, `stage_id` |
223| Deals in stage | `PIPEDRIVE_GET_DEALS_IN_A_STAGE` | `id`, `start`, `limit` |
224| Add product to deal | `PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL` | `id`, `product_id`, `item_price` |
225