Drip MCP Server

# Drip MCP Server A Model Context Protocol (MCP) server that enables Claude Code and other MCP clients to interact with Drip's email marketing platform. This server provides comprehensive tools for managing subscribers, campaigns, tags, events, and workflows. ## Features ### Core Capabilities - **Subscriber Management**: Create, update, list, fetch, and unsubscribe subscribers - **Tag Management**: Apply and remove tags for segmentation - **Event Tracking**: Record custom events for behavioral triggers - **Campaign Management**: List campaigns, subscribe/unsubscribe users from email series - **Workflow Automation**: List, activate, pause workflows, and start subscribers on workflows - **Batch Operations**: Efficiently handle bulk subscriber updates - **Custom Fields**: List and manage custom field identifiers ### Smart Features - **Dual Response Formats**: All tools support both JSON (for processing) and Markdown (for readability) - **Pagination Support**: Handle large datasets efficiently with built-in pagination - **Character Limit Protection**: Automatic response truncation with helpful guidance - **Comprehensive Error Handling**: Clear, actionable error messages - **GDPR Compliance**: Built-in support for EU consent management ## Installation ### Prerequisites - Python 3.8 or higher - Drip account with API access - MCP-compatible client (e.g., Claude Code) ### Quick Install We provide installation helper scripts to make setup easier: #### Option 1: Python Installation Helper (Recommended) ```bash python scripts/install_helper.py ``` #### Option 2: Bash Installation Script ```bash chmod +x scripts/install.sh ./scripts/install.sh ``` #### Option 3: Manual Installation ### Step 1: Clone or Download ```bash # Save the files to your desired directory mkdir ~/drip-mcp cd ~/drip-mcp ``` ### Step 2: Install Dependencies ```bash pip install httpx pydantic # Install MCP SDK (try one of these methods): pip install mcp # If that doesn't work, try from GitHub: pip install git+https://github.com/modelcontextprotocol/python-sdk.git # Or clone and install locally: git clone https://github.com/modelcontextprotocol/python-sdk.git cd python-sdk pip install -e . cd .. ``` ### Step 3: Set Environment Variables ```bash # Get these from your Drip account export DRIP_API_KEY='your-api-key-here' export DRIP_ACCOUNT_ID='your-account-id-here' ``` **Finding Your Credentials:** - **API Key**: Drip Dashboard → Settings → My User Settings → API Token - **Account ID**: Look at your Drip dashboard URL (the number in the URL) ### Step 4: Test the Server ```bash # Test that the server starts correctly python -m drip_mcp.server --help # Or run the test script python tests/test_server.py ``` ## Usage with Claude Code ### Configure Claude Code Add the following to your Claude Code configuration file (`~/.config/claude/claude_config.json` or equivalent): ```json { "mcpServers": { "drip": { "command": "python", "args": ["-m", "drip_mcp.server"], "cwd": "/absolute/path/to/drip_mcp", "env": { "DRIP_API_KEY": "your-api-key", "DRIP_ACCOUNT_ID": "your-account-id", "PYTHONPATH": "/absolute/path/to/drip_mcp/src" } } } } ``` See `docs/claude_code_config_example.json` for a complete configuration example. ### Example Commands in Claude Code Once configured, you can use natural language to interact with Drip: ``` // Subscriber Management "Add john@example.com to Drip with the tag 'Customer'" "List all active subscribers" "Show me details for jane@example.com" "Unsubscribe user@example.com from all emails" // Tag Management "Apply the 'VIP' tag to customer@example.com" "Show me all tags in my Drip account" "Remove the 'Trial' tag from user@example.com" // Event Tracking "Record a 'Started Trial' event for new@example.com" "Track a purchase of $99.99 for customer@example.com" "List all custom events we're tracking" // Campaign Management "List all active email campaigns" "Subscribe lead@example.com to campaign 123456" "Remove subscriber@example.com from all campaigns" // Workflow Automation "Show me all workflows" "Activate workflow 789012" "Start john@example.com on the onboarding workflow" // Batch Operations "Import these 50 subscribers from a CSV" "Update tags for multiple subscribers at once" ``` ## Available Tools ### Subscriber Management - `drip_create_update_subscriber` - Create or update a subscriber - `drip_list_subscribers` - List subscribers with filtering - `drip_fetch_subscriber` - Get detailed subscriber information - `drip_unsubscribe_from_all` - Globally unsubscribe a subscriber - `drip_batch_subscribe` - Batch create/update up to 1000 subscribers ### Tag Management - `drip_list_tags` - List all tags in the account - `drip_apply_tag` - Apply a tag to a subscriber - `drip_remove_tag` - Remove a tag from a subscriber ### Event Tracking - `drip_record_event` - Record a custom event for a subscriber - `drip_list_event_actions` - List all event types being tracked ### Campaign Management - `drip_list_campaigns` - List Email Series Campaigns - `drip_subscribe_to_campaign` - Subscribe someone to a campaign - `drip_unsubscribe_from_campaign` - Remove from campaign(s) ### Workflow Management - `drip_list_workflows` - List all workflows - `drip_activate_workflow` - Activate a workflow - `drip_pause_workflow` - Pause a workflow - `drip_start_on_workflow` - Start a subscriber on a workflow ### Utility Tools - `drip_list_custom_fields` - List custom field identifiers ## Tool Parameters Most tools support these common parameters: ### Response Format - `response_format`: Choose between "markdown" (human-readable) or "json" (machine-readable) ### Pagination - `page`: Page number (starts at 1) - `per_page`: Results per page (max 100) ### Filtering - `status`: Filter by subscriber/campaign status - `tags`: Filter by tags (comma-separated) - `sort`: Sort results by different fields ## Examples ### Python Script Usage ```python import asyncio import sys sys.path.insert(0, 'src') # Add src to path from drip_mcp import create_update_subscriber, SubscriberCreateUpdateInput async def main(): # Create a subscriber params = SubscriberCreateUpdateInput( email="newuser@example.com", first_name="John", last_name="Doe", tags=["Customer", "Newsletter"], custom_fields={"company": "Acme Corp"}, response_format="markdown" ) result = await create_update_subscriber(params) print(result) asyncio.run(main()) ``` ### Common Workflows #### 1. Import and Tag Subscribers ```python # Batch import with tags subscribers = [ {"email": "user1@example.com", "tags": ["Import-Jan-2024"]}, {"email": "user2@example.com", "tags": ["Import-Jan-2024", "VIP"]} ] await batch_subscribe(subscribers) ``` #### 2. Track Customer Journey ```python # Record multiple events for a subscriber await record_event({ "email": "customer@example.com", "action": "Viewed Product", "properties": {"product_id": "SKU123", "category": "Electronics"} }) await record_event({ "email": "customer@example.com", "action": "Made Purchase", "properties": {"value": 9999} # $99.99 in cents }) ``` #### 3. Segment and Campaign Management ```python # Apply tags and subscribe to campaign await apply_tag({"email": "lead@example.com", "tag": "Interested-In-Demo"}) await subscribe_to_campaign({ "campaign_id": "123456", "email": "lead@example.com", "double_optin": True }) ``` ## Error Handling The server provides clear error messages for common issues: - **Missing Credentials**: Warns if environment variables are not set - **API Errors**: Returns detailed error messages from Drip API - **Rate Limiting**: Handles Drip's rate limits (50 batch requests/hour, 3600 individual/hour) - **Validation Errors**: Pydantic validates all inputs before API calls ## Best Practices 1. **Use Batch Operations**: For multiple subscribers, use `drip_batch_subscribe` instead of individual calls 2. **Respect Rate Limits**: 50 batch requests/hour, 3600 individual requests/hour 3. **Use Tags for Segmentation**: Tags are powerful for triggering automations 4. **Track Events with Properties**: Include relevant data in event properties 5. **Choose Appropriate Response Format**: Use JSON for processing, Markdown for reading 6. **Handle Pagination**: Use page parameters for large result sets ## Troubleshooting ### Server Won't Start - Check Python version: `python --version` (needs 3.8+) - Verify dependencies: `pip list | grep -E "mcp|httpx|pydantic"` - Check environment variables: `echo $DRIP_API_KEY` ### ImportError: FastMCP If you see `ImportError: cannot import name 'FastMCP'`: - The MCP SDK might not be properly installed - Try installing from GitHub: `pip install git+https://github.com/modelcontextprotocol/python-sdk.git` - Or clone and install locally: ```bash git clone https://github.com/modelcontextprotocol/python-sdk.git cd python-sdk pip install -e . ``` ### Authentication Errors - Verify API key is correct and active - Check account ID matches your Drip account - Ensure API key has necessary permissions ### Connection Issues - Check internet connectivity - Verify Drip API is accessible: `curl https://api.getdrip.com/v2/accounts` - Check for proxy/firewall restrictions ## Advanced Configuration ### Custom Character Limit Edit the `CHARACTER_LIMIT` constant in `src/drip_mcp/server.py` to adjust response size limits: ```python CHARACTER_LIMIT = 50000 # Increase for larger responses ``` ### Custom User Agent Modify the `get_auth_headers()` function to set a custom User-Agent: ```python "User-Agent": "YourApp/1.0 (Drip MCP Server)" ``` ## Security Notes - **Never commit API keys**: Use environment variables or secure key management - **Validate inputs**: The server uses Pydantic for input validation - **HTTPS only**: All API communication uses HTTPS - **Limited scope**: Tools are designed with appropriate read/write hints ## Support and Resources - **Drip API Documentation**: https://developer.drip.com/ - **MCP Specification**: https://modelcontextprotocol.io/ - **Drip Help Center**: https://help.drip.com/ ## License This MCP server is provided as-is for use with Drip's API. Ensure you comply with Drip's API terms of service and rate limits. ## Contributing To contribute improvements: 1. Test changes thoroughly with a Drip test account 2. Follow MCP best practices for tool design 3. Update documentation for new features 4. Ensure backward compatibility ## Version History - **1.0.1** - Codebase refactoring and improvements - **Restructured project**: Organized into `src/`, `tests/`, `scripts/`, and `docs/` directories - **Removed unnecessary files**: Deleted incorrect `package.json` and `pnpm-lock.yaml` - **Added `pyproject.toml`**: Modern Python packaging with proper dependencies - **Updated imports**: Main module now at `src/drip_mcp/server.py` - Fixed compatibility with FastMCP (removed unsupported annotations parameter) - Added installation helper scripts - Improved error handling for MCP SDK installation - Enhanced `.gitignore` with comprehensive Python patterns - **Breaking change**: Server path changed - update Claude Code config to use `python -m drip_mcp.server` - **1.0.0** - Initial release with core Drip functionality - Subscriber management - Campaign and workflow tools - Tag and event tracking - Batch operations support ### Project Structure Note As of v1.0.1, the project follows Python best practices with a hierarchical structure. Main source code is in `src/drip_mcp/`, tests in `tests/`, utilities in `scripts/`, and documentation in `docs/`. If upgrading from v1.0.0, update your Claude Code configuration to point to the new server path.