489 lines
16 KiB
Markdown
489 lines
16 KiB
Markdown
# 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.
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.typescriptlang.org/)
|
|
[](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**
|