Skip to main content

Installation

To get your MCP server running you need to start with these two steps:

  • Installing Docker
  • Configuring the AI agent

Docker​

  1. Install and run Docker: https://docs.docker.com/desktop/

  2. Optional: pull the MCP Docker image. The image will be pulled automatically when you start the AI agent. However, if you prefer to ensure it's available ahead of time or avoid any delay during the initial startup, you can pull it manually

    docker pull woodpeckerco/woodpecker-mcp-server

AI agent​

Claude​

The following steps are specific to Claude Desktop

  1. Locate the Claude Desktop configuration file

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

    Windows:
    %APPDATA%\Claude\claude_desktop_config.json

    Linux:
    ~/.config/Claude/claude_desktop_config.json

  2. Add MCP server configuration

    Edit the configuration file to include the Woodpecker MCP server. Replace {YOUR_API_KEY}with your Woodpecker API key

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

  3. Restart Claude Desktop if it was running

  4. Verifiy and test

    You can look for the Woodpecker tools in the interface, or directly ask the AI agent:

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

Other AI agents​

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

Troubleshooting​

MCP server not connecting

Symptoms: AI agent can't access Woodpecker tools

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

Invalid API credentials

Symptoms: "Unauthorized" or "Invalid API key" errors

  • Regenerate API key in Woodpecker marketplace
  • Update environment variables with new key
  • Restart AI Agent application

Tools not available

Symptoms: AI agent doesn't see Woodpecker functions

  • Check MCP server configuration in AI agent
  • Restart AI agent application
  • Check AI agent logs for MCP connection errors

Campaign creation fails

Symptoms: Error when creating campaigns

  • Ensure you have at least one email account connected to Woodpecker
  • Verify email account IDs with listMailboxes function
  • Check whether campaign parameters match required format
  • Ensure daily enrollment limit is > 0