# Pipedrive Leads MCP

> Pipedrive Leads manages your entire lead lifecycle—creating, updating, and organizing prospects directly from your AI client. This server lets you read all existing leads (`pd_list_leads`), pull specific details (`pd_get_lead`), or make bulk changes to labels and sources before they enter the sales pipeline.

## Overview
- **Category:** lead-generation
- **Price:** Free
- **Tags:** lead-management, lead-scoring, prospecting, sales-funnel

## Description

This server hooks your Pipedrive CRM straight into your AI client. You won't have to jump between browser tabs or manually update anything in the sales funnel again. Your agent gets full visibility across every single lead, letting you manage records—creating them, updating them, and cleaning up junk—just by giving simple instructions.

**Building Leads and Records:** When you need a new prospect in Pipedrive, your agent uses `pd_create_lead` to build the record. It handles all the initial data points for that brand-new lead right away. If a lead changes status or needs a name fix, you tell it what's wrong, and the agent executes `pd_update_lead`, changing specific details like the stage or updating the person's name on an existing account.

**Cleaning Up:** Got leads that are dead ends? You don't wanna keep 'em cluttering up your pipeline. Your agent runs `pd_delete_lead` to remove old records from Pipedrive entirely, keeping your data clean and actionable.

**Checking the Status Quo:** Wanna see what's going on with all your prospects right now? You ask for a list of current leads, and the agent fires off `pd_list_leads`. This gives you an immediate overview and status check on multiple leads at once. If you need to dig deep into one specific prospect—say, you gotta review every detail about Lead ID 54321—the agent uses `pd_get_lead` to pull all the granular information for that single lead.

**Managing Metadata:** Before you update anything, you gotta make sure your tags and sources are right. You can check out what categories of labels exist by calling `pd_lead_labels`, which lists every available label category you've set up in Pipedrive. Similarly, if you wanna know where incoming leads are coming from, the agent uses `pd_lead_sources` to retrieve a full list of defined sources. This lets your AI client verify proper tagging before it makes any changes to records.

**Workflow Examples:** You can tell your agent: 'Pull all current leads, then for the ones labeled 'Hot' that are coming from 'Website', update their stage to 'Qualified'.'

The server manages this whole sequence. It first runs `pd_list_leads` to gather the necessary status data; it checks available categories with `pd_lead_labels`; and once everything lines up, it executes `pd_update_lead` for every record that matches your criteria.

You can't just update names or stages; you gotta get the metadata straight first. If you don't know what labels are valid, calling `pd_lead_labels` stops you from using a typo and messing up your data structure. It makes sure everything stays tight.

For example, if a lead is coming in through an old channel, you can run `pd_lead_sources` to see the exact source name needed before running `pd_update_lead`. If that specific ID isn't found or needs more info, calling `pd_get_lead` pulls every single detail point so your agent knows exactly what it’s dealing with. This eliminates guesswork.

It keeps everything organized. You tell the agent to build a lead, and it uses `pd_create_lead`. If that lead turns out to be irrelevant after review, you just say delete, and it runs `pd_delete_lead`. That's how easy this is. It handles the whole cycle: creation via `pd_create_lead`, status check via `pd_list_leads` or deep dive with `pd_get_lead`, organization using `pd_lead_sources` and `pd_lead_labels`, modification with `pd_update_lead`, and cleanup with `pd_delete_lead`. You'll stop wasting time clicking around Pipedrive. Your AI client does the heavy lifting for you.

## Tools

### pd_create_lead
Creates a brand new lead record within your Pipedrive account.

### pd_delete_lead
Removes an existing lead from the Pipedrive system.

### pd_get_lead
Retrieves all detailed information for a single, specified lead ID.

### pd_lead_labels
Lists every available label category you can apply to leads.

### pd_list_leads
Fetches an overview and status list of multiple leads from your inbox.

### pd_lead_sources
Retrieves a list of all defined sources for incoming leads.

### pd_update_lead
Changes specific data points, like the name or stage, on an existing lead record.

## Prompt Examples

**Prompt:** 
```
Search for deals with Acme Corp
```

**Response:** 
```
📊 **Deals with Acme Corp**
| Title | Value | Stage | Pipeline |
|---|---|---|---|
| Acme Enterprise License | $45,000 | Proposal Made | Sales Pipeline |
| Acme Support Plan | $12,000 | Won | Renewals |
```

**Prompt:** 
```
Create a call activity for tomorrow at 2pm
```

**Response:** 
```
✅ **Activity Created!**
- Type: Call
- Subject: Follow-up call
- Due: Tomorrow at 2:00 PM
- Status: Pending
```

**Prompt:** 
```
Show me the pipeline stages
```

**Response:** 
```
📦 **Sales Pipeline**
1. Lead In
2. Contact Made
3. Prospect Qualified
4. Proposal Made
5. Negotiations Started
6. Won ✅
7. Lost ❌
```

## Capabilities

### Create and Modify Leads
The agent builds, updates, or deletes specific leads in Pipedrive by invoking `pd_create_lead`, `pd_update_lead`, or `pd_delete_lead`.

### Review Lead Status
You ask for a list of all current prospects, and the agent runs `pd_list_leads` to give you an overview.

### Retrieve Specific Details
Need info on one lead? The agent uses `pd_get_lead` to fetch precise details for review or modification.

### Manage Lead Metadata
The system checks available categories by calling `pd_lead_labels` and `pd_lead_sources`, ensuring you use proper tagging before updating records.

## Use Cases

### The Post-Conference Cleanup
A SDR just ran through 50 business cards at a trade show. Instead of manually entering each one into Pipedrive, they ask their agent to use `pd_create_lead` for all 50 contacts and tag them using the 'Trade Show XYZ' source found via `pd_lead_sources`. This gets everything into the system instantly.

### Checking Up on a Hot Deal
A Sales Rep needs to check if Acme Corp is still in the right pipeline stage. They run `pd_get_lead` for Acme's ID, pulling up the last recorded notes and confirming its status before sending the next proposal.

### Mass Data Scrubbing
The RevOps analyst finds a batch of leads that are marked as 'Unknown Source'. They use `pd_list_leads` to pull the IDs, then check available labels with `pd_lead_labels`. Finally, they run `pd_update_lead` on all relevant records to apply the correct 'Webinar' label.

### Pipeline Review Before Handoff
A Sales Manager reviews a list of prospects. They use `pd_list_leads` and ask the agent to filter for leads that haven't been touched in 30 days, identifying who needs an immediate follow-up call.

## Benefits

- Stop manually switching tabs. You can view a list of all leads using `pd_list_leads` and immediately initiate an action—like updating their status—all from one window.
- Never guess what tags to use again. Calling `pd_lead_labels` gives you the full, current menu of available labels before you run any updates with `pd_update_lead`.
- Streamline prospecting by creating new records. Use `pd_create_lead` and automatically assign it a proper source via `pd_lead_sources`, ensuring clean data from day one.
- Get instant deep dives into single prospects. Instead of digging through the UI, run `pd_get_lead` to pull all necessary contact details or activity notes instantly.
- Clean up your backlog fast. When leads are dead ends, use `pd_delete_lead`. It's a simple command that removes clutter without any manual navigation.

## How It Works

The bottom line is you tell your AI client what needs to happen in Pipedrive, and it handles the sequence of API calls required to get it done.

1. You tell your AI client: 'Find me all leads from the recent XYZ conference, and change their status to 'Qualified'.'
2. The agent first checks available tags by calling `pd_lead_labels` and then runs a search using `pd_list_leads`. It gathers the necessary IDs.
3. Finally, it executes `pd_update_lead` for every relevant record, confirming that the status change went through.

## Frequently Asked Questions

**How do I list all my current leads using pd_list_leads?**
Just tell your AI client to run `pd_list_leads`. The agent will pull a summary of all your active leads and give you an overview, so you can quickly identify who needs attention.

**Can pd_update_lead change the lead's source?**
Yes. If a lead was mis-sourced, you use `pd_get_lead` to verify its current details first, and then run `pd_update_lead` to correct the source information.

**What is pd_lead_labels used for?**
It shows you every available label category in Pipedrive. You use this list to ensure that when you create or update a lead, you pick an exact, correct tag.

**Should I run pd_create_lead before listing leads?**
No. You use `pd_list_leads` first if you are checking existing data. Only call `pd_create_lead` when you have a brand new lead to add to the system.

**If I use `pd_get_lead` with a lead ID that doesn't exist, what error code should I expect?**
The tool returns an explicit 'Not Found' status (e.g., 404). You must confirm the lead ID is active in Pipedrive before calling this function. The agent will fail cleanly if the record isn't there.

**Does `pd_list_leads` paginate results when I have thousands of leads?**
Yes, it supports pagination logic. When running a list query on many records, you need to pass parameters that tell the agent how to fetch subsequent pages. Don't rely on one single call for large datasets.

**What are the mandatory fields I must include when using `pd_create_lead`?**
You generally need a lead name and at least an email address to successfully create a record. While other details are recommended, these two fields are key for the system to register the new entry.

**When I call `pd_delete_lead`, is the data permanently removed from Pipedrive?**
No, the action typically soft-deletes the lead. The record moves to a 'trash' state within Pipedrive instead of being instantly purged. You can usually restore it before permanent deletion.

**What Pipedrive data can I access?**
Deals, Persons, Organizations, Activities, Notes, and Pipelines. All data respects your Pipedrive permissions.

**Can I create and update records?**
Yes! Create and update deals, contacts, activities, and notes — all through natural conversation.

**How does authentication work?**
Uses your personal Pipedrive API token. Find it in Settings > Personal preferences > API. No OAuth flow needed.