Pipedrive FastMCP Server

A comprehensive Model Context Protocol (MCP) server that exposes the complete Pipedrive API v1 as OpenAPI-based MCP tools using the FastMCP framework. This enables AI assistants to interact seamlessly with Pipedrive CRM data.

🚀 Features

• Complete API Coverage: 28 tools covering all major Pipedrive entities
• OpenAPI-based: Built following Pipedrive's official OpenAPI v1 specification
• FastMCP Framework: Modern, efficient MCP server implementation
• Secure Authentication: Token-based authentication with environment variable management
• Real-time Data: Direct integration with live Pipedrive data
• Comprehensive CRUD: Full Create, Read, Update, Delete operations for core entities

📋 Available Tools

🔹 Deals (6 tools)

• get_deals - List all deals with filtering options
• get_deal_by_id - Get specific deal by ID
• create_deal - Create new deal
• update_deal - Update existing deal
• delete_deal - Delete deal

🔹 Persons/Contacts (6 tools)

• get_persons - List all persons/contacts
• get_person_by_id - Get specific person by ID
• create_person - Create new person/contact
• update_person - Update existing person
• delete_person - Delete person

🔹 Organizations (6 tools)

• get_organizations - List all organizations
• get_organization_by_id - Get specific organization by ID
• create_organization - Create new organization
• update_organization - Update existing organization
• delete_organization - Delete organization

🔹 Activities (2 tools)

• get_activities - List all activities with filtering
• create_activity - Create new activity/task

🔹 Pipelines (3 tools)

• get_pipelines - List all sales pipelines
• get_pipeline_by_id - Get specific pipeline by ID
• get_pipeline_deals - Get deals within a pipeline

🔹 Users (2 tools)

• get_users - List all users
• get_current_user - Get current user information

🔹 Search (1 tool)

• search_items - Search across all Pipedrive items

🔹 Resources (1 resource)

• pipedrive://info - Server information and help

🛠️ Installation & Setup

Prerequisites

• Python 3.11+
• Pipedrive account with API access
• Pipedrive API token

1. Environment Setup

The server runs automatically in Replit. For local development:

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env

2. Get Your Pipedrive API Token

1. Log into your Pipedrive account
2. Go to Settings → Personal preferences → API
3. Copy your API token
4. Set the environment variable:

export PIPEDRIVE_API_TOKEN="your_api_token_here"

3. Run the Server

python main.py

The server will start and listen for MCP connections via STDIO transport.

🔧 Configuration

Environment Variables

• PIPEDRIVE_API_TOKEN (required): Your Pipedrive API token
• PIPEDRIVE_COMPANY_DOMAIN (optional): Your company domain (defaults to 'api')

MCP Client Configuration

To connect an MCP-compatible AI assistant:

{
  "mcpServers": {
    "pipedrive": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token_here"
      }
    }
  }
}

💡 Usage Examples

Basic Queries

"Show me all open deals"
"Create a new contact named John Doe with email john@example.com"
"Find all companies with 'tech' in the name"
"What are my sales pipelines?"
"Create a $5000 deal with Acme Corp"

Advanced Operations

"Show me all activities for this week"
"Get all deals assigned to user ID 123"
"Update deal 456 to the next stage"
"Find all contacts at Microsoft and their recent activities"
"Give me conversion rates for each pipeline stage"

Data Analysis

"Summarize all won deals this quarter"
"Show me the top 10 highest value deals"
"Which organizations have the most active deals?"
"What activities are overdue?"

📚 API Reference

All tools follow the Pipedrive API v1 specification:

• Base URL: https://api.pipedrive.com/v1
• Authentication: API token via query parameter
• Documentation: https://developers.pipedrive.com/docs/api/v1

Response Format

All tools return JSON responses with either:

• Success: The requested data from Pipedrive
• Error: {"error": "Description of what went wrong"}

Pagination

List endpoints support pagination:

• start: Starting offset (default: 0)
• limit: Items per page (default: 100, max: 500)

Filtering

Many endpoints support filtering:

• user_id: Filter by user
• filter_id: Apply saved filter
• status: Filter by status
• Date ranges and more

🔒 Security

• API tokens are securely handled via environment variables
• No tokens are logged or exposed in responses
• All API calls use HTTPS
• Follows Pipedrive's security best practices

🚀 Deployment

Production Deployment

The server is configured for VM deployment and will run as a long-running process:

# The server runs continuously via STDIO transport
python main.py

Integration with AI Assistants

This MCP server works with any MCP-compatible AI assistant:

• Claude (via MCP client)
• Cursor
• Other MCP clients

Configure your AI assistant to connect to this server for seamless Pipedrive integration.

📁 File Structure

├── main.py              # Core MCP server implementation
├── mcp.json            # MCP manifest with tool definitions
├── examples.py         # Usage examples and patterns
├── requirements.txt    # Python dependencies
├── pipedrive_openapi.yaml  # Pipedrive OpenAPI specification
├── .env.example        # Environment variable template
├── .gitignore         # Git ignore patterns
└── README.md          # This documentation

🤝 Contributing

This server implements the complete Pipedrive API v1 specification. For additional features or improvements:

1. Check the Pipedrive API documentation
2. Follow the existing code patterns
3. Add comprehensive error handling
4. Update the MCP manifest (mcp.json)

📖 Resources

• FastMCP Documentation
• Model Context Protocol
• Pipedrive API Reference
• Pipedrive OpenAPI Spec

📜 License

MIT License - see LICENSE file for details.

---

Built with FastMCP 🚀 | Powered by Pipedrive API v1 🔌