# Pipedrive MCP (`was-pipedrive-mcp`)

A self-contained, cross-platform Model Context Protocol (MCP) server for Pipedrive CRM. Exposes 27 tools allowing AI coding assistants (Claude Desktop, Cursor, Antigravity, VS Code, Zed, etc.) to read, create, update, search, and manage Pipedrive deals, contacts, activities, organizations, leads, and pipelines. Built by Web Analytics Solution.

## Prerequisites

| | Required | How to install |
|---|---|---|
| **Node.js 18+** | running `npx` | Mac: `brew install node` · Windows: https://nodejs.org · Linux: `apt install nodejs npm` |
| **Git** | letting `npx` clone from GitHub | Mac: `brew install git` (or first `git --version` triggers Xcode tools) · Windows: https://git-scm.com · Linux: `apt install git` |
| **Pipedrive account** | to access CRM data | [Sign up here](https://www.pipedrive.com/) |
| **Personal API token** | for API authentication | Walked through below |

## Quick Start — 3 Steps

### Step 1 — Get Credentials

1. Log in to your Pipedrive account.
2. Click on your profile icon in the top right corner and select **Settings** (or **Personal preferences**).
3. Navigate to the **API** tab.
4. Copy your **Personal API token** (or click **Generate token** if you don't have one yet).

### Step 2 — Connect

Run the interactive authentication command in your terminal:

```bash
npx -y github:mnsmasum62786/was-pipedrive-mcp auth
```

Paste your API token when prompted. The CLI will automatically verify your token against Pipedrive (`/users/me`) and save it locally with secure `0600` permissions at `~/.was-pipedrive-mcp/config.json`.

### Step 3 — Add to Your AI Client

Add the following configuration to your AI client's MCP configuration JSON file:

```json
{
  "mcpServers": {
    "Pipedrive MCP": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-pipedrive-mcp"]
    }
  }
}
```

#### Configuration File Locations by Client:
- **Claude Desktop (Mac)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor**: `~/.cursor/mcp.json` (or via Cursor Settings -> MCP)
- **Google Antigravity / Windsurf**: `~/.gemini/antigravity/mcp.json` or `~/.codeium/windsurf/mcp_config.json`

## What You Can Ask the AI

Here are example prompts you can use in your AI chat once connected:

### Discovery & Inspection
- *"Who am I logged in as in Pipedrive, and what company account is this?"*
- *"List all sales pipelines and their stages in my Pipedrive account."*
- *"List all users in our Pipedrive company account."*

### Sales Pipeline & Deals
- *"Show me the top 10 open deals in Pipedrive right now."*
- *"Search for any deals related to 'Enterprise Upgrade'."*
- *"Create a new deal titled 'Acme Corp Q3 Renewal' valued at $15,000 USD in stage ID 2."*
- *"Move deal ID 45 to 'won' status."*

### Contacts & Organizations
- *"Find contact persons with the name 'Jane Doe' or email 'jane@example.com'."*
- *"Create a new organization called 'TechStream Inc' located in Austin, TX."*
- *"Create a new contact person named 'John Smith' associated with organization ID 12 and phone '555-0199'."*

### Activities & Leads
- *"List my scheduled activities and calls due this week."*
- *"Create a follow-up call activity for deal ID 45 due tomorrow at 14:00."*
- *"Mark activity ID 88 as completed."*
- *"Create a new lead in the Leads Inbox titled 'Inbound Web Inquiry - Acme Corp'."*

## All Tools (27 Total)

| Category | Tools | Description |
|---|---|---|
| **Users & Account** | `pd_get_me`, `pd_list_users` | Inspect authenticated profile and company users. |
| **Deals** | `pd_list_deals`, `pd_get_deal`, `pd_create_deal`, `pd_update_deal`, `pd_delete_deal`, `pd_search_deals` | Full CRUD, filtering, and text search for sales pipeline deals. |
| **Persons (Contacts)** | `pd_list_persons`, `pd_get_person`, `pd_create_person`, `pd_update_person`, `pd_delete_person`, `pd_search_persons` | Manage individual contact persons and their contact details. |
| **Organizations** | `pd_list_organizations`, `pd_get_organization`, `pd_create_organization`, `pd_update_organization`, `pd_search_organizations` | Manage company accounts and addresses. |
| **Activities** | `pd_list_activities`, `pd_create_activity`, `pd_update_activity` | Schedule and complete tasks, calls, meetings, and emails. |
| **Leads** | `pd_list_leads`, `pd_create_lead` | Manage early-stage leads in the Leads Inbox. |
| **Pipelines & Stages** | `pd_list_pipelines`, `pd_list_stages` | Inspect pipeline structure and stage IDs. |
| **Escape Hatch** | `pd_api` | Invoke any Pipedrive REST API v1 endpoint directly (`GET`, `POST`, `PUT`, `DELETE`). |

## CLI Commands

You can run these commands directly via `npx -y github:mnsmasum62786/was-pipedrive-mcp <command>`:

- `auth` — Interactive prompt to connect or re-connect your Pipedrive API token.
- `status` — Show config file path, verification status, and timestamp of saved credentials.
- `logout` — Delete the locally stored credentials file (`~/.was-pipedrive-mcp/config.json`).
- `help` — Print command line usage and environment variable instructions.

## Multi-Account Setup

Power users can bypass the local config file by setting environment variables. This allows running multiple Pipedrive accounts simultaneously by defining separate entries in your AI client config:

```json
{
  "mcpServers": {
    "Pipedrive Account A": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-pipedrive-mcp"],
      "env": {
        "PIPEDRIVE_API_KEY": "token_for_account_a"
      }
    },
    "Pipedrive Account B": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-pipedrive-mcp"],
      "env": {
        "PIPEDRIVE_API_KEY": "token_for_account_b"
      }
    }
  }
}
```

## Troubleshooting

### 1. "Pipedrive MCP — not configured yet"
- **Cause**: The server was started without running the authentication setup.
- **Fix**: Open your terminal and run `npx -y github:mnsmasum62786/was-pipedrive-mcp auth`.

### 2. HTTP 401 or Verification Failed during setup
- **Cause**: The Personal API token pasted is incorrect or has been revoked in Pipedrive.
- **Fix**: Check Settings -> Personal preferences -> API in Pipedrive, generate a new token, and run `auth` again.

### 3. Windows PowerShell Execution Policy Error
If you see an error like `npx.ps1 cannot be loaded because running scripts is disabled`:
- **Fix**: Run the following command in PowerShell:
  ```powershell
  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
  ```

### 4. Old Code / Cached Version after Update
Windows and Mac may cache older npx bundles. To force clear the npx cache and pull the latest release:
- **Windows (PowerShell)**:
  ```powershell
  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache" -ErrorAction SilentlyContinue
  npm cache clean --force
  ```
- **Mac / Linux**:
  ```bash
  rm -rf ~/.npm/_npx
  npm cache clean --force
  ```

## License

MIT License. Built by [Web Analytics Solution](https://webanalyticsbd.com/).