Woodpecker MCP Server

The Woodpecker MCP (Model Context Protocol) integration transforms cold email campaign management into a conversational experience.

By connecting your AI assistant to Woodpecker’s powerful automation platform, you can create, manage and optimize email campaigns through natural language interactions.

Start with simple commands like listing campaigns and creating basic outreach sequences. Then gradually explore advanced features like A/B testing, complex follow-up sequences and detailed analytics reporting.

Features

• Campaign Management: Create, update, run, pause and delete email campaigns
• Prospect Operations: Add prospects to campaigns, update prospect data
• Email Composition: Create multistep email sequences with A/B testing capabilities
• Analytics & Reporting: Retrieve campaign statistics and performance metrics
• Mailbox Integration: Assign email accounts to campaigns
• Advanced Configuration: Support for delivery schedules, timezone settings and GDPR compliance

Installation

Prerequisites

Before setting up the integration, ensure you have:

• Woodpecker Account: An account with the API & Integration add-on enabled
• API Credentials: Woodpecker API key (found in your account settings)
• Docker: Installed on your system (for running the MCP server) https://docs.docker.com/desktop/
• AI Agent: Claude Desktop, Continue.dev or another MCP-compatible AI platform

Getting Your Woodpecker API Key

1. Log in to the Woodpecker account (https://login.woodpecker.co/)
2. Go to the Marketplace in the top-right corner → Integrations → ‘API keys’
3. Click Create a key

AI Agent Configuration

Claude Desktop

Step 1: Locate Configuration File

Find your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%Claudeclaude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Step 2: Add MCP Server Configuration

Edit the configuration file to include the Woodpecker MCP server:

{
    "mcpServers": {
        "woodpecker": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "WOODPECKER_API_KEY",
                "woodpeckerco/woodpecker-mcp-server"
            ],
            "env": {
                "WOODPECKER_API_KEY": "<YOUR_API_KEY>"
            }
        }
    }
}

Step 3: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Restart the application
3. Look for the Woodpecker tools in the interface

Other MCP-Compatible Agents

For other AI platforms that support MCP:

1. Ensure MCP Support: Verify your AI agent supports the Model Context Protocol
2. Authentication: Provide Woodpecker API credentials (WOODPECKER_API_KEY) through environment variables
3. Protocol: Use stdio transport as supported by your agent

Verification and Testing

In your AI agent, try asking:

"What Woodpecker tools do you have access to?"
"List my Woodpecker campaigns"

Troubleshooting

MCP Server Not Connecting

Symptoms: AI agent can’t access Woodpecker tools

Solutions:

1. Try absolute Docker path (e.g. /usr/local/bin/docker) in MCP Server Configuration
2. Check if Docker container is running: docker ps
3. Test API key: Make direct API call to Woodpecker

Invalid API Credentials

Symptoms: “Unauthorized” or “Invalid API key” errors

Solutions:

1. Regenerate API key in Woodpecker settings
2. Update environment variables with new key
3. Restart AI Agent application

Tools Not Available

Symptoms: AI agent doesn’t see Woodpecker functions

Solutions:

1. Check MCP server configuration in AI agent
2. Restart AI agent application
3. Check AI agent logs for MCP connection errors

Campaign Creation Fails

Symptoms: Error when creating campaigns

Solutions:

1. Ensure you have at least one email account configured in Woodpecker
2. Verify email account IDs with listMailboxes function
3. Check campaign parameters match required format
4. Ensure daily enrollment limit is > 0

Usage Examples

Creating Your First Campaign

"Create a new email campaign with these details:
- Name: Product Demo Outreach
- Subject: Quick demo of our new feature
- Message: Hi {{FIRST_NAME}}, I'd love to show {{COMPANY}} our new feature. Are you available for a 15-minute demo?
- Send Monday-Friday, 9 AM to 5 PM
- Daily limit: 25 prospects
- Use my main email account"

Adding Prospects in Bulk

"Add these prospects to campaign 12345:
1. John Doe, john@example.com, Example Corp, Marketing Director
2. Jane Smith, jane@example.com, Tech Solutions, CEO
3. Bob Johnson, bob@example.com, Startup Inc, CTO

Use this personalization for each:
- John: 'I saw your recent blog post about email marketing'
- Jane: 'Congratulations on your recent funding round'
- Bob: 'Your product launch looked impressive'"

Campaign Management

"Pause campaign 12345 and show me its performance statistics"
"Update campaign 'Product Demo Outreach' to send only 15 prospects per day"
"Add a follow-up email to campaign 12345 that sends 3 days after the first email"

Analytics and Reporting

"Show me statistics for all my running campaigns"
"Which campaign has the highest open rate?"
"Create a summary report of my campaign performance this month"

Best Practices

Campaign Management

1. Start Small: Test with 5-10 prospects before scaling
2. Monitor Performance: Check statistics regularly
3. Respect Limits: Stay within daily enrollment limits
4. A/B Testing: Use multiple email versions for optimization

Prospect Data

1. Data Quality: Ensure email addresses are valid
2. Personalization: Use meaningful snippets and custom fields
3. Segmentation: Organize prospects with tags and industries
4. Compliance: Include unsubscribe links and respect opt-outs

AI Agent Interactions

1. Be Specific: Provide clear instructions for campaign creation
2. Verify Results: Check campaign details before running
3. Use Examples: Include sample content and personalization
4. Monitor Automation: Review AI-generated campaigns before deployment

Support

Contact Woodpecker Support Team at Woodpecker Support

License

Permission is granted to use this Docker image for personal and commercial purposes. Redistribution, modification and reverse engineering are prohibited. No warranty is provided.

Copyright 2025 Woodpecker.co S.A.

Available Tools

Campaign Management

createCampaign

Create campaigns with basic configuration including subjects, messages and delivery settings. Supports full templating with snippets, fallbacks and spintax for personalized content.

Parameters:

• name (string): Campaign name
• subjects (array): Email subject lines
• messages (array): Email body content
• emailAccountIds (array): SMTP account IDs
• timezone (string): Campaign timezone
• dailyEnroll (number): Daily prospect enrollment limit
• deliveryDays (array): Days of the week for sending
• deliveryTimeStart/Stop (string): Sending time window
• trackOpens (boolean): Enable open tracking

createAdvancedCampaign

Create campaigns with full API capabilities including A/B testing and complex delivery schedules.

Parameters:

• campaignPayload (string): Complete campaign configuration JSON

listCampaigns

Retrieve campaigns with optional status filtering.

Parameters:

• pageNumber (number): Page number (1-based)
• statuses (array): Filter by status (RUNNING, DRAFT, PAUSED, STOPPED, COMPLETED)

retrieveCampaignDetails

Get detailed campaign structure including all steps and configurations.

Parameters:

• campaignId (number): Campaign ID

retrieveCampaignStatistics

Fetch campaign performance metrics and analytics.

Parameters:

• campaignId (number): Campaign ID

updateCampaignSettings

Modify campaign-wide settings including name, email accounts, daily limits and timezone.

Parameters:

• campaignId (number): Campaign ID
• name (string): Campaign name
• emailAccountIds (array): List of email account IDs
• timezone (string): Campaign timezone
• dailyEnroll (number): Daily enrollment limit

buildCampaignUrl

Generate Woodpecker app URL for campaign access.

Parameters:

• campaignId (number): Campaign ID

Campaign Control

• runCampaign(campaignId): Start campaign execution
• pauseCampaign(campaignId): Pause campaign
• stopCampaign(campaignId): Stop campaign
• deleteCampaign(campaignId): Remove campaign entirely
• makeCampaignEditable(campaignId): Enable campaign modifications

Email Step Management

addStep

Add follow-up steps to existing campaigns.

Parameters:

• campaignId (number): Campaign ID
• payload (string): Step configuration JSON

updateCampaignStep

Modify step delivery times and scheduling.

Parameters:

• campaignId (number): Campaign ID
• stepId (string): Step ID
• payload (string): Updated delivery configuration

updateStepVersion

Update email content, subject lines, signatures and tracking settings.

Parameters:

• campaignId (number): Campaign ID
• stepId (string): Step ID
• versionId (string): Version ID
• subject (string): Email subject
• message (string): Email body (HTML supported)
• signature (string): SENDER or NO_SIGNATURE
• trackOpens (boolean): Enable open tracking

deleteCampaignStep

Remove steps from campaigns.

Parameters:

• campaignId (number): Campaign ID
• stepId (string): Step ID

Prospect Operations

addProspectsToCampaign

Bulk add prospects with full contact information and custom snippets.

Parameters:

• campaignId (number): Campaign ID
• prospectsPayload (string): Array of prospect objects

Note: Always check for DUPLICATE prospects in response. Use updateProspectsInCampaign for duplicates if data updates are needed.

updateProspectsInCampaign

Update existing prospect data (requires explicit user request).

Parameters:

• campaignId (number): Campaign ID
• prospectsPayload (string): Array of prospect objects with updates

listProspectsInCampaign

Paginated retrieval of campaign prospects.

Parameters:

• campaignId (number): Campaign ID
• pageNumber (number): Page number (1-based)

Account Management

listMailboxes

Retrieve available email accounts for campaign assignment.

Parameters: None

Documentation

• Woodpecker API: https://developers.woodpecker.co/docs/
• MCP Protocol: https://modelcontextprotocol.io
• Claude Desktop: https://claude.ai/download