From 9d85ddcac7e19bee725e28dbd58f17fa24607b2e Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Thu, 12 Feb 2026 17:12:30 -0500 Subject: [PATCH] pipedrive: 118 tools, 27 apps, README --- servers/pipedrive/README.md | 488 ++++++++++++++++++++++++++++++++ servers/pipedrive/src/client.ts | 4 +- servers/pipedrive/tsconfig.json | 2 +- 3 files changed, 491 insertions(+), 3 deletions(-) create mode 100644 servers/pipedrive/README.md diff --git a/servers/pipedrive/README.md b/servers/pipedrive/README.md new file mode 100644 index 0000000..257b7b3 --- /dev/null +++ b/servers/pipedrive/README.md @@ -0,0 +1,488 @@ +# 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 +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** diff --git a/servers/pipedrive/src/client.ts b/servers/pipedrive/src/client.ts index 47052c1..38e8d75 100644 --- a/servers/pipedrive/src/client.ts +++ b/servers/pipedrive/src/client.ts @@ -150,7 +150,7 @@ export class PipedriveClient { if (!response.ok) { let errorBody: string; try { - const json = await response.json(); + const json = await response.json() as any; errorBody = json.error || json.message || JSON.stringify(json); } catch { errorBody = await response.text().catch(() => "Unable to read error body"); @@ -163,7 +163,7 @@ export class PipedriveClient { } try { - const json = await response.json(); + const json = await response.json() as any; // Pipedrive wraps responses in { success: true, data: ... } if (json.success === false) { throw new ApiError( diff --git a/servers/pipedrive/tsconfig.json b/servers/pipedrive/tsconfig.json index ddba8da..bd7e7cb 100644 --- a/servers/pipedrive/tsconfig.json +++ b/servers/pipedrive/tsconfig.json @@ -17,5 +17,5 @@ "allowSyntheticDefaultImports": true }, "include": ["src/**/*"], - "exclude": ["node_modules", "dist"] + "exclude": ["node_modules", "dist", "src/ui", "src/apps"] }