# Pipedrive MCP Server

A Model Context Protocol (MCP) server for Pipedrive CRM. This server allows LLMs like Claude to interact with your Pipedrive data through a standardized interface.

Developed by [Osher Digital](https://osher.com.au/)

## Features

- **22 Tools** for comprehensive Pipedrive access
- **Saved Filter Support**: Use Pipedrive's saved filters to query by custom fields
- **Field Definitions**: Map custom field hashes to human-readable names
- **Activities**: Access calls, meetings, tasks, and emails
- **Flexible Sorting**: Sort deals by date, value, or title
- **Date Range Filtering**: Filter by created/updated dates
- **Rate Limiting**: Built-in rate limiting to respect Pipedrive API limits

## Installation

```bash
cd pipedrive-mcp-python

# Install with uv
uv sync
```

## Configuration

Create a `.env` file in the project root (or set environment variables):

```env
# Required
PIPEDRIVE_API_TOKEN=your_api_token_here
PIPEDRIVE_DOMAIN=your-company.pipedrive.com

# Optional - Rate Limiting
PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS=250
PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT=2
```

### Getting Your API Token

1. Log into your Pipedrive account
2. Go to **Settings > Personal preferences > API**
3. Copy your API token

## Usage

### Running the Server

```bash
# Run with uv
uv run pipedrive-mcp
```

### Claude Desktop Integration

Add to your Claude Desktop configuration:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pipedrive": {
      "command": "/path/to/pipedrive-mcp-python/.venv/bin/python",
      "args": ["-m", "pipedrive_mcp.server"],
      "cwd": "/path/to/pipedrive-mcp-python"
    }
  }
}
```

Set environment variables in your shell profile or `.env` file in the project directory.

### Claude Code CLI Integration

```bash
claude mcp add pipedrive -- /path/to/pipedrive-mcp-python/.venv/bin/python -m pipedrive_mcp.server
```

## Available Tools (22)

### User Management

| Tool | Description |
|------|-------------|
| `get_users()` | Get all users/owners from Pipedrive |

### Deals

| Tool | Description |
|------|-------------|
| `get_deals(...)` | Get deals with comprehensive filtering (see below) |
| `get_deal(deal_id)` | Get a single deal by ID with all custom fields |
| `get_deal_notes(deal_id)` | Get notes for a specific deal |
| `search_deals(term, limit)` | Full-text search deals |

**`get_deals` parameters:**
- `search_title` - Search by deal title (partial matches)
- `owner_id` - Filter by owner/user ID
- `stage_id` - Filter by pipeline stage
- `status` - Filter by status: `open`, `won`, `lost`, `deleted` (default: `open`)
- `pipeline_id` - Filter by pipeline
- `filter_id` - Use a saved filter from Pipedrive
- `min_value` / `max_value` - Filter by deal value range
- `created_after` / `created_before` - Filter by creation date (ISO format: YYYY-MM-DD)
- `updated_after` / `updated_before` - Filter by update date
- `sort_by` - Sort field: `add_time`, `update_time`, `title`, `value` (default: `add_time`)
- `sort_order` - Sort direction: `asc`, `desc` (default: `desc`)
- `limit` - Maximum results (default: 500)

### Persons (Contacts)

| Tool | Description |
|------|-------------|
| `get_persons(filter_id, limit)` | Get all persons, optionally filtered by saved filter |
| `get_person(person_id)` | Get a single person by ID with all custom fields |
| `search_persons(term, limit)` | Full-text search persons |

### Organizations

| Tool | Description |
|------|-------------|
| `get_organizations(filter_id, limit)` | Get all organizations, optionally filtered |
| `get_organization(org_id)` | Get a single organization by ID |
| `search_organizations(term, limit)` | Full-text search organizations |

### Pipelines & Stages

| Tool | Description |
|------|-------------|
| `get_pipelines()` | Get all sales pipelines |
| `get_pipeline(pipeline_id)` | Get a single pipeline by ID |
| `get_stages(pipeline_id)` | Get all stages, optionally filtered by pipeline |

### Leads

| Tool | Description |
|------|-------------|
| `search_leads(term, limit)` | Full-text search leads |

### Universal Search

| Tool | Description |
|------|-------------|
| `search_all(term, item_types, limit)` | Search across all item types |

**Supported item types:** `deal`, `person`, `organization`, `product`, `file`, `activity`, `lead`

### Filters

| Tool | Description |
|------|-------------|
| `get_filters(filter_type)` | Get all saved filters from Pipedrive |

**Filter types:** `deals`, `persons`, `org`, `products`, `activities`

Use saved filters to query by custom fields:
1. Create a filter in Pipedrive UI with your criteria
2. Call `get_filters()` to find the filter's ID
3. Pass `filter_id` to `get_persons()`, `get_deals()`, or `get_organizations()`

### Field Definitions

| Tool | Description |
|------|-------------|
| `get_deal_fields()` | Get deal field definitions (maps hash IDs to names) |
| `get_person_fields()` | Get person field definitions |
| `get_organization_fields()` | Get organization field definitions |

These tools map custom field hash keys (like `c3976c9693716fc786c2092081506816441ee526`) to human-readable field names.

### Activities

| Tool | Description |
|------|-------------|
| `get_activities(...)` | Get activities (calls, meetings, tasks, emails) |
| `get_activity_types()` | Get all activity types configured in Pipedrive |

**`get_activities` parameters:**
- `deal_id` - Filter by deal
- `person_id` - Filter by person
- `org_id` - Filter by organization
- `user_id` - Filter by assigned user
- `activity_type` - Filter by type (call, meeting, task, email, etc.)
- `done` - Filter by completion status (`True`/`False`)
- `start_date` / `end_date` - Filter by date range (ISO format)
- `limit` - Maximum results (default: 100)

## Examples

### Get 10 most recent deals
```
get_deals(limit=10)
```

### Get deals created this year
```
get_deals(created_after="2026-01-01")
```

### Get highest value deals
```
get_deals(sort_by="value", sort_order="desc", limit=10)
```

### Get contacts matching a saved filter
```
get_filters(filter_type="persons")  # Find the filter ID
get_persons(filter_id=122)          # Use the filter
```

### Get all calls for a specific deal
```
get_activities(deal_id=123, activity_type="call")
```

### Understand a custom field
```
get_deal_fields()  # Returns mapping of hash keys to field names
```

## Development

```bash
# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run with verbose output
uv run pytest -v
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Attribution

Developed by [Osher Digital](https://osher.com.au/) - Digital transformation and AI integration specialists.