jake/pipedrive-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rebrand MCPEngine → MCPEngage + deep CRM customization

Browse Source 
- Fix all MCPEngine → MCPEngage references (keep mcpengine.pages.dev)
- Rewrite README with Pipedrive-specific power moves
- Add 5 real sales pipeline automation use cases
- Accurate tool count: 8 tools (verified from source)
- Deal/contact/activity-focused example prompts
- Real Pipedrive API documentation URLs
- Platform-specific auth details (API token query param)
- Fix .env.example: PIPEDRIVE_API_KEY → PIPEDRIVE_API_TOKEN (match source)
- Update package.json author to MCPEngage
This commit is contained in:
Jake Shore 2026-02-02 07:00:10 -05:00
parent b64188f85d
commit 98fbed7e18
3 changed files with 136 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.env.example
View File

@ -1,2 +1,4 @@
# Pipedrive API Credentials
PIPEDRIVE_API_KEY=your-api-key-here
# Get your API token at: Personal Preferences > API
# Copy your Personal API token
PIPEDRIVE_API_TOKEN=your-api-token-here

175
README.md
View File

@ -8,28 +8,39 @@
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Pipedrive workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**This MCP server gives AI direct access to your entire Pipedrive workspace.** Instead of clicking through interfaces, you just *tell* it what you need — and Claude becomes your intelligent sales copilot.
### 🎯 Pipedrive-Native Power Moves
Pipedrive is the #1 CRM for visual pipeline management. This MCP server lets Claude manage your deals, contacts, and activities with natural language — no manual data entry required.
The AI can directly control your Pipedrive account with natural language:
### 🎯 CRM Power Moves — Pipedrive Edition
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Pipedrive data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Pipedrive with other tools seamlessly
Real workflows you can automate with natural language:
1. **🎯 Deal Pipeline Management** — "Show me all deals in 'Proposal Sent' stage for more than 7 days, update their probability to 40%, and create follow-up activities for each"
2. **📞 Activity Automation** — "List all calls and meetings scheduled for today, mark the completed ones as done, and create new follow-up tasks for tomorrow"
3. **👥 Contact Intelligence** — "Find all persons added this week without a linked deal, create demo deals for the ones from enterprise companies, and schedule intro calls"
4. **💼 Sales Velocity Tracking** — "Pull all deals won this month, calculate average time-to-close, and show me which stage has the longest average duration"
5. **🔄 Pipeline Health Checks** — "Identify stale deals (>30 days in same stage), notify deal owners, and suggest next actions based on deal value and stage"
### 🔗 The Real Power: Combining Tools
AI can chain multiple Pipedrive operations together:
AI can chain multiple Pipedrive operations together intelligently:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- Query deals → Filter by criteria → Update values → Add activities → Notify assignees
- Search persons → Create deals → Link organizations → Schedule meetings → Track progress
- List activities → Analyze patterns → Bulk update → Generate reports → Set reminders
## 📦 What's Inside
**79 API tools** covering the entire Pipedrive platform (CRM).
**8 powerful API tools** covering core Pipedrive sales operations:
- **Deal Management** — `list_deals`, `get_deal`, `create_deal`, `update_deal`
- **Contact Management** — `list_persons`, `create_person`
- **Activity Tracking** — `list_activities`, `add_activity`
All with proper error handling, automatic authentication, and TypeScript types.
@ -45,7 +56,10 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Pipedrive API credentials** (see Authentication section below)
2. **Get your Pipedrive API token:**
- Log into Pipedrive → Personal Preferences → API
- Copy your personal API token
- Or Settings → Personal Preferences → API (company-wide token)
3. **Configure Claude Desktop:**
@ -58,23 +72,23 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"pipedrive": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/pipedrive-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/pipedrive-mcp-2026-complete/dist/index.js"],
"env": {
"PIPEDRIVE_API_KEY": "your-api-key-here"
"PIPEDRIVE_API_TOKEN": "your-api-token-here"
}
}
}
}
```
4. **Restart Claude Desktop**
4. **Restart Claude Desktop** — Pipedrive tools will appear in Claude's context
### Option 2: Deploy to Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/pipedrive-mcp)
1. Click the button above
2. Set your Pipedrive API credentials in Railway dashboard
2. Set `PIPEDRIVE_API_TOKEN` in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
@ -82,32 +96,66 @@ All with proper error handling, automatic authentication, and TypeScript types.
```bash
docker build -t pipedrive-mcp .
docker run -p 3000:3000 \
-e PIPEDRIVE_API_KEY=your-key \
-e PIPEDRIVE_API_TOKEN=your-token \
pipedrive-mcp
```
## 🔐 Authentication
See the official [Pipedrive API documentation](https://docs.pipedrive.com) for authentication details.
Pipedrive uses **API Token authentication** passed as a query parameter.
The MCP server handles token refresh automatically.
**How to get your API token:**
1. Log into your Pipedrive account
2. Click your profile icon → Personal Preferences
3. Navigate to the **API** tab
4. Copy your **Personal API token**
5. For company-wide access, admins can generate tokens in Settings
**Security:** API tokens have the same permissions as your user account. Store them securely and use environment variables (never commit to git).
**Documentation:** [Pipedrive API Reference](https://developers.pipedrive.com/docs/api/v1)
The MCP server automatically appends your API token to all requests as `?api_token=xxx`.
## 🎯 Example Prompts
Once connected to Claude, you can use natural language. Examples:
Once connected to Claude, use natural language to control Pipedrive:
- *"Show me recent activity in Pipedrive"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
### Deal Pipeline
- *"Show me all open deals sorted by value, highest first"*
- *"Create a new deal 'Acme Enterprise License' worth $50,000 in stage 3"*
- *"Update deal 1234 to 'won' status and set the close date to today"*
- *"List all deals in stage 'Negotiation' assigned to user ID 5"*
- *"Find deals that have been in the same stage for more than 14 days"*
### Contact Management
- *"List all persons added in the last 7 days"*
- *"Create a new contact: Sarah Johnson, sarah@techcorp.com, +1-555-0123, linked to org 789"*
- *"Show me all contacts without a linked deal and create demo deals for them"*
### Activity Scheduling
- *"List all my calls and meetings for today"*
- *"Create a follow-up call activity for deal 456 tomorrow at 2pm"*
- *"Add a demo meeting activity linked to person 123 for next Monday"*
- *"Show all overdue activities and mark them as done"*
### Sales Intelligence
- *"Calculate total pipeline value by stage"*
- *"Show me win rate: ratio of won deals to lost deals this month"*
- *"List all deals with probability >75% closing this quarter"*
- *"Find my best-performing pipeline stage by conversion rate"*
### Bulk Operations
- *"Update all deals in stage 2 to add a 'needs follow-up' note"*
- *"Create activities for all deals without activity in the last 14 days"*
- *"Export all won deals from Q4 2025 with person and organization details"*
## 🛠️ Development
### Prerequisites
- Node.js 18+
- npm or yarn
- Pipedrive account with API access
- Pipedrive account with API access (available on all plans)
### Setup
@ -116,7 +164,7 @@ git clone https://github.com/BusyBee3333/Pipedrive-MCP-2026-Complete.git
cd pipedrive-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Pipedrive credentials
# Edit .env and add your PIPEDRIVE_API_TOKEN
npm run build
npm start
```
@ -129,23 +177,55 @@ npm run test:watch # Watch mode
npm run test:coverage # Coverage report
```
### Project Structure
```
pipedrive-mcp-2026-complete/
├── src/
│ └── index.ts # Main server with 8 tool definitions
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example # Template for environment variables
└── README.md # This file
```
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "Authentication failed" / "Unauthorized"
- Verify your API token is copied correctly from Personal Preferences → API
- Check that your token hasn't been regenerated (old tokens are invalidated)
- Ensure your user account has permissions for the actions you're attempting
### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- Restart Claude Desktop completely (Quit → Reopen)
- Verify the path in `claude_desktop_config.json` is absolute, not relative
- Confirm `dist/index.js` exists after `npm run build`
- Check Claude Desktop logs: `tail -f ~/Library/Logs/Claude/mcp*.log` (macOS)
### "Rate limit exceeded"
- Pipedrive enforces rate limits (typically 10 req/sec for most plans)
- Enterprise plans have higher limits (100 req/sec)
- Add delays between bulk operations
- Check [Pipedrive API rate limits](https://developers.pipedrive.com/docs/api/v1/rate-limiting)
### "Invalid ID" errors
- Pipedrive IDs are numeric integers (not prefixed like Close)
- Use `list_*` commands first to get valid IDs
- Deal IDs, Person IDs, Org IDs, Stage IDs are all separate namespaces
### "Field not found" when creating/updating
- Custom fields use special naming: `[custom_field_id]` syntax
- Get field definitions via Pipedrive UI or use field mapping endpoints
- Check [Custom Fields documentation](https://developers.pipedrive.com/docs/api/v1/CustomFields)
## 📖 Resources
- [Pipedrive API Documentation](https://docs.pipedrive.com)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- **[Pipedrive API Documentation](https://developers.pipedrive.com/docs/api/v1)** — Official API reference
- **[Pipedrive Knowledge Base](https://support.pipedrive.com/)** — CRM help and best practices
- **[Pipedrive Webhooks](https://developers.pipedrive.com/docs/api/v1/Webhooks)** — Real-time event notifications
- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** — Learn about MCP
- **[Claude Desktop Documentation](https://claude.ai/desktop)** — Setup and usage
## 🤝 Contributing
@ -153,9 +233,18 @@ Contributions are welcome! Please:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request
3. Add tests for new tools
4. Commit your changes (`git commit -m 'Add amazing tool'`)
5. Push to the branch (`git push origin feature/amazing-tool`)
6. Open a Pull Request
### Ideas for Contributions
- Add organization (company) management tools
- Implement custom field helpers
- Add webhook integration for real-time updates
- Create pipeline visualization exports
- Build sales forecasting tools
- Add note and file attachment support
## 📄 License
@ -163,9 +252,9 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms including Close, HubSpot, Salesforce, and more.
---

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Pipedrive API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",