# Pipedrive MCP Server

**The most comprehensive Model Context Protocol (MCP) server for Pipedrive CRM** — built with 118 production-ready tools and 27 rich UI applications.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12-green)](https://github.com/modelcontextprotocol)

## 🚀 Features

- **118 Production-Ready Tools** — Complete Pipedrive API coverage across 16 functional areas
- **27 Rich UI Apps** — Interactive React dashboards, grids, analytics, and management interfaces
- **Full CRUD Operations** — Create, read, update, delete, search, and bulk operations
- **Advanced Analytics** — Pipeline metrics, revenue tracking, conversion funnels, goal progress
- **Webhook Management** — Subscribe to real-time events, manage subscriptions
- **Rate Limiting** — Built-in API rate limit handling with automatic retries
- **Type-Safe** — Full TypeScript implementation with strict type checking
- **Extensible** — Modular architecture makes it easy to add custom tools

## 📦 Installation

### From npm (coming soon)

```bash
npm install -g pipedrive-mcp
```

### From Source

```bash
git clone <repository-url>
cd servers/pipedrive
npm install
npm run build
```

## 🔧 Configuration

### MCP Settings (Claude Desktop, Continue, etc.)

Add to your MCP configuration file:

```json
{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "pipedrive-mcp"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your-api-token-here",
        "PIPEDRIVE_COMPANY_DOMAIN": "your-company"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PIPEDRIVE_API_TOKEN` | Yes | Your Pipedrive API token (Settings → API → Personal preferences) |
| `PIPEDRIVE_COMPANY_DOMAIN` | Yes | Your Pipedrive company domain (e.g., `mycompany` from `mycompany.pipedrive.com`) |

### Getting Your API Token

1. Log in to Pipedrive
2. Go to **Settings** → **Personal preferences**
3. Click **API** tab
4. Copy your Personal API token

## 🛠️ Tool Categories (118 Tools)

### 1. Deals (11 tools)
- `pipedrive_deals_list` — List all deals with filtering
- `pipedrive_deals_get` — Get specific deal details
- `pipedrive_deals_create` — Create new deal
- `pipedrive_deals_update` — Update deal details
- `pipedrive_deals_delete` — Delete deal
- `pipedrive_deals_search` — Search deals by term
- `pipedrive_deals_duplicate` — Duplicate existing deal
- `pipedrive_deals_merge` — Merge two deals
- `pipedrive_deals_followers_list` — List deal followers
- `pipedrive_deals_followers_add` — Add follower to deal
- `pipedrive_deals_products` — Manage deal products

### 2. Persons (10 tools)
- `pipedrive_persons_list` — List all persons
- `pipedrive_persons_get` — Get person details
- `pipedrive_persons_create` — Create new person
- `pipedrive_persons_update` — Update person
- `pipedrive_persons_delete` — Delete person
- `pipedrive_persons_search` — Search persons
- `pipedrive_persons_merge` — Merge two persons
- `pipedrive_persons_deals` — Get person's deals
- `pipedrive_persons_followers` — Manage person followers
- `pipedrive_persons_picture` — Manage person picture

### 3. Organizations (9 tools)
- `pipedrive_organizations_list` — List all organizations
- `pipedrive_organizations_get` — Get organization details
- `pipedrive_organizations_create` — Create new organization
- `pipedrive_organizations_update` — Update organization
- `pipedrive_organizations_delete` — Delete organization
- `pipedrive_organizations_search` — Search organizations
- `pipedrive_organizations_merge` — Merge two organizations
- `pipedrive_organizations_deals` — Get org's deals
- `pipedrive_organizations_persons` — Get org's persons

### 4. Activities (10 tools)
- `pipedrive_activities_list` — List all activities
- `pipedrive_activities_get` — Get activity details
- `pipedrive_activities_create` — Create new activity
- `pipedrive_activities_update` — Update activity
- `pipedrive_activities_delete` — Delete activity
- `pipedrive_activities_bulk_delete` — Delete multiple activities
- `pipedrive_activities_bulk_update` — Update multiple activities
- `pipedrive_activities_types_list` — List activity types
- `pipedrive_activities_types_create` — Create activity type
- `pipedrive_activities_types_update` — Update activity type

### 5. Pipelines (6 tools)
- `pipedrive_pipelines_list` — List all pipelines
- `pipedrive_pipelines_get` — Get pipeline details
- `pipedrive_pipelines_create` — Create new pipeline
- `pipedrive_pipelines_update` — Update pipeline
- `pipedrive_pipelines_delete` — Delete pipeline
- `pipedrive_pipelines_deals` — Get pipeline deals

### 6. Stages (8 tools)
- `pipedrive_stages_list` — List all stages
- `pipedrive_stages_get` — Get stage details
- `pipedrive_stages_create` — Create new stage
- `pipedrive_stages_update` — Update stage
- `pipedrive_stages_delete` — Delete stage
- `pipedrive_stages_deals` — Get stage deals
- `pipedrive_stages_reorder` — Reorder stages
- `pipedrive_stages_conversion` — Get conversion stats

### 7. Products (8 tools)
- `pipedrive_products_list` — List all products
- `pipedrive_products_get` — Get product details
- `pipedrive_products_create` — Create new product
- `pipedrive_products_update` — Update product
- `pipedrive_products_delete` — Delete product
- `pipedrive_products_search` — Search products
- `pipedrive_products_deals` — Get product deals
- `pipedrive_products_followers` — Manage followers

### 8. Leads (9 tools)
- `pipedrive_leads_list` — List all leads
- `pipedrive_leads_get` — Get lead details
- `pipedrive_leads_create` — Create new lead
- `pipedrive_leads_update` — Update lead
- `pipedrive_leads_delete` — Delete lead
- `pipedrive_leads_search` — Search leads
- `pipedrive_leads_labels` — Manage lead labels
- `pipedrive_leads_sources` — Manage lead sources
- `pipedrive_leads_convert` — Convert lead to deal

### 9. Notes (6 tools)
- `pipedrive_notes_list` — List all notes
- `pipedrive_notes_get` — Get note details
- `pipedrive_notes_create` — Create new note
- `pipedrive_notes_update` — Update note
- `pipedrive_notes_delete` — Delete note
- `pipedrive_notes_comments` — Manage note comments

### 10. Files (7 tools)
- `pipedrive_files_list` — List all files
- `pipedrive_files_get` — Get file details
- `pipedrive_files_create` — Upload new file
- `pipedrive_files_update` — Update file details
- `pipedrive_files_delete` — Delete file
- `pipedrive_files_download` — Download file
- `pipedrive_files_link` — Link file to entity

### 11. Filters (6 tools)
- `pipedrive_filters_list` — List all filters
- `pipedrive_filters_get` — Get filter details
- `pipedrive_filters_create` — Create new filter
- `pipedrive_filters_update` — Update filter
- `pipedrive_filters_delete` — Delete filter
- `pipedrive_filters_apply` — Apply filter to data

### 12. Goals (7 tools)
- `pipedrive_goals_list` — List all goals
- `pipedrive_goals_get` — Get goal details
- `pipedrive_goals_create` — Create new goal
- `pipedrive_goals_update` — Update goal
- `pipedrive_goals_delete` — Delete goal
- `pipedrive_goals_results` — Get goal results
- `pipedrive_goals_progress` — Track goal progress

### 13. Webhooks (6 tools)
- `pipedrive_webhooks_list` — List all webhooks
- `pipedrive_webhooks_get` — Get webhook details
- `pipedrive_webhooks_create` — Create new webhook
- `pipedrive_webhooks_update` — Update webhook
- `pipedrive_webhooks_delete` — Delete webhook
- `pipedrive_webhooks_test` — Test webhook

### 14. Users (5 tools)
- `pipedrive_users_list` — List all users
- `pipedrive_users_get` — Get user details
- `pipedrive_users_current` — Get current user
- `pipedrive_users_permissions` — Get user permissions
- `pipedrive_users_followers` — Manage user followers

### 15. Mail (8 tools)
- `pipedrive_mail_threads_list` — List mail threads
- `pipedrive_mail_threads_get` — Get thread details
- `pipedrive_mail_messages_list` — List messages
- `pipedrive_mail_messages_get` — Get message details
- `pipedrive_mail_send` — Send new email
- `pipedrive_mail_sync` — Sync mail account
- `pipedrive_mail_folders` — Manage folders
- `pipedrive_mail_settings` — Manage settings

### 16. Subscriptions (12 tools)
- `pipedrive_subscriptions_list` — List all subscriptions
- `pipedrive_subscriptions_get` — Get subscription details
- `pipedrive_subscriptions_create` — Create subscription
- `pipedrive_subscriptions_update` — Update subscription
- `pipedrive_subscriptions_delete` — Delete subscription
- `pipedrive_subscriptions_payments` — Track payments
- `pipedrive_subscriptions_recurring` — Manage recurring
- `pipedrive_subscriptions_addons` — Manage add-ons
- `pipedrive_subscriptions_pause` — Pause subscription
- `pipedrive_subscriptions_resume` — Resume subscription
- `pipedrive_subscriptions_cancel` — Cancel subscription
- `pipedrive_subscriptions_renew` — Renew subscription

## 🎨 UI Applications (27 Apps)

### Deals & Pipeline Management
1. **deal-dashboard** — Executive dashboard with key deal metrics
2. **deal-detail** — Detailed deal view with timeline and activities
3. **deal-grid** — Sortable, filterable deal grid with bulk actions
4. **deals-timeline** — Visual timeline of deal progression
5. **pipeline-kanban** — Drag-and-drop kanban board for deals
6. **pipeline-analytics** — Pipeline health, conversion rates, forecasting
7. **pipeline-funnel** — Conversion funnel visualization
8. **won-deals** — Celebration board of closed-won deals

### People & Organizations
9. **person-detail** — Comprehensive person profile
10. **person-grid** — People database with advanced filtering
11. **org-detail** — Organization profile with related entities
12. **org-grid** — Organizations table with search

### Activities & Communication
13. **activity-calendar** — Calendar view of all activities
14. **activity-dashboard** — Activity metrics and insights
15. **email-inbox** — Mail threads and messages viewer
16. **lead-inbox** — Lead management interface
17. **lead-detail** — Detailed lead view with conversion tracking

### Products & Revenue
18. **product-catalog** — Product library with pricing
19. **product-detail** — Product details with deal history
20. **revenue-dashboard** — Revenue analytics and forecasts
21. **subscription-manager** — Subscription lifecycle management

### Content & Organization
22. **note-manager** — Notes library with search and tags
23. **file-manager** — File repository with previews
24. **filter-manager** — Create and manage custom filters

### Analytics & Reporting
25. **goal-tracker** — Goals progress and achievement tracking
26. **user-stats** — User performance metrics
27. **search-results** — Universal search across all entities

## 📖 Usage Examples

### Creating a Deal

```javascript
// Using MCP tool
pipedrive_deals_create({
  title: "Enterprise Deal - Acme Corp",
  value: 50000,
  currency: "USD",
  person_id: 123,
  org_id: 456,
  pipeline_id: 1,
  stage_id: 2,
  expected_close_date: "2024-12-31"
})
```

### Searching for Contacts

```javascript
// Search persons by email
pipedrive_persons_search({
  term: "john@example.com",
  fields: "email",
  exact_match: true
})
```

### Getting Pipeline Analytics

```javascript
// Get pipeline metrics
pipedrive_pipelines_get({
  id: 1,
  totals_convert_currency: "USD"
})

// Get stage conversion rates
pipedrive_stages_conversion({
  pipeline_id: 1,
  start_date: "2024-01-01",
  end_date: "2024-12-31"
})
```

### Managing Activities

```javascript
// Create a meeting
pipedrive_activities_create({
  subject: "Product Demo",
  type: "meeting",
  due_date: "2024-06-15",
  due_time: "14:00",
  duration: "01:00",
  deal_id: 789,
  person_id: 123
})

// List today's activities
pipedrive_activities_list({
  start_date: "2024-06-12",
  end_date: "2024-06-12",
  user_id: 1
})
```

### Setting Up Webhooks

```javascript
// Subscribe to deal updates
pipedrive_webhooks_create({
  subscription_url: "https://your-app.com/webhooks/pipedrive",
  event_action: "updated",
  event_object: "deal"
})

// List all webhooks
pipedrive_webhooks_list()
```

### Working with Products

```javascript
// Add product to deal
pipedrive_deals_products({
  deal_id: 789,
  product_id: 456,
  item_price: 99.99,
  quantity: 10
})

// Search products by SKU
pipedrive_products_search({
  term: "SKU-12345",
  fields: "code"
})
```

## 🏗️ Architecture

```
servers/pipedrive/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── client.ts             # Pipedrive API client
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # 16 tool modules (118 tools)
│   │   ├── deals-tools.ts
│   │   ├── persons-tools.ts
│   │   ├── organizations-tools.ts
│   │   ├── activities-tools.ts
│   │   ├── pipelines-tools.ts
│   │   ├── stages-tools.ts
│   │   ├── products-tools.ts
│   │   ├── leads-tools.ts
│   │   ├── notes-tools.ts
│   │   ├── files-tools.ts
│   │   ├── filters-tools.ts
│   │   ├── goals-tools.ts
│   │   ├── webhooks-tools.ts
│   │   ├── users-tools.ts
│   │   ├── mail-tools.ts
│   │   └── subscriptions-tools.ts
│   ├── apps/                 # 27 UI apps (React)
│   │   ├── deal-dashboard.ts
│   │   ├── pipeline-kanban.ts
│   │   ├── revenue-dashboard.ts
│   │   └── ... (24 more)
│   └── ui/
│       └── react-app/        # React source for apps
├── package.json
├── tsconfig.json
└── README.md
```

## 🔌 API Client Features

The built-in API client (`PipedriveClient`) provides:

- **Automatic rate limiting** — Respects Pipedrive API limits
- **Retry logic** — Auto-retry on rate limit and transient errors
- **Type safety** — Full TypeScript support
- **Error handling** — Descriptive error messages
- **Pagination** — Automatic pagination handling
- **Authentication** — Secure API token management

## 🧪 Development

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Clean Build

```bash
npm run clean && npm run build
```

### Type Checking

```bash
npx tsc --noEmit
```

## 📝 License

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

## 🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 📚 Resources

- [Pipedrive API Documentation](https://developers.pipedrive.com/docs/api/v1)
- [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## 🆘 Support

For issues and questions:
- Open an issue on GitHub
- Check [Pipedrive Developer Community](https://devcommunity.pipedrive.com/)
- Review [MCP Documentation](https://modelcontextprotocol.io/docs)

## 🎯 Roadmap

- [ ] Additional webhook event handlers
- [ ] Custom field management tools
- [ ] Advanced search operators
- [ ] Bulk import/export capabilities
- [ ] Real-time collaboration features
- [ ] Enhanced analytics and reporting
- [ ] Custom dashboard builder
- [ ] Workflow automation tools

---

**Built with ❤️ for the MCP ecosystem**