pipedrive-mcp-2026-complete/README.md

> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/pipedrive)
> 
> Zero setup. Zero maintenance. Just connect and automate.

---

# 🚀 Pipedrive MCP Server — 2026 Complete Version

## 💡 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 — and Claude becomes your intelligent sales copilot.

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.

### 🎯 CRM Power Moves — Pipedrive Edition

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 intelligently:

- 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

**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.

## 🚀 Quick Start

### Option 1: Claude Desktop (Local)

1. **Clone and build:**
   ```bash
   git clone https://github.com/BusyBee3333/Pipedrive-MCP-2026-Complete.git
   cd pipedrive-mcp-2026-complete
   npm install
   npm run build
   ```

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:**
   
   On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   
   On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "pipedrive": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/pipedrive-mcp-2026-complete/dist/index.js"],
         "env": {
           "PIPEDRIVE_API_TOKEN": "your-api-token-here"
         }
       }
     }
   }
   ```

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 `PIPEDRIVE_API_TOKEN` in Railway dashboard
3. Use the Railway URL as your MCP server endpoint

### Option 3: Docker

```bash
docker build -t pipedrive-mcp .
docker run -p 3000:3000 \
  -e PIPEDRIVE_API_TOKEN=your-token \
  pipedrive-mcp
```

## 🔐 Authentication

Pipedrive uses **API Token authentication** passed as a query parameter.

**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, use natural language to control Pipedrive:

### 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 (available on all plans)

### Setup

```bash
git clone https://github.com/BusyBee3333/Pipedrive-MCP-2026-Complete.git
cd pipedrive-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env and add your PIPEDRIVE_API_TOKEN
npm run build
npm start
```

### Testing

```bash
npm test                  # Run all tests
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" / "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 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://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

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
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

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

## 🙏 Credits

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 including Close, HubSpot, Salesforce, and more.

---

**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).