From 98fbed7e18c8198f0494ca6f3482d104d65bed2b Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 07:00:10 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20deep=20CRM=20customization?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .env.example | 4 +- README.md | 175 ++++++++++++++++++++++++++++++++++++++------------- package.json | 2 +- 3 files changed, 136 insertions(+), 45 deletions(-) diff --git a/.env.example b/.env.example index 63c1bd4..4779c10 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index 35843ac..20e6e85 100644 --- a/README.md +++ b/README.md @@ -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. --- diff --git a/package.json b/package.json index 3ba09bb..982beae 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Pipedrive API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",