Run the Woodpecker MCP server locally

Run the Woodpecker MCP server with Docker if you want to host it yourself, connect it to an MCP client that supports stdio, or use it with client accounts managed under a Woodpecker Agency account.

This setup requires:

A Woodpecker account with the API & Integration add-on enabled
A Woodpecker API key
Docker

You can use the Docker server with Claude Desktop, Cursor, Gemini CLI, or another MCP client that supports the stdio transport.

Start Docker

Install and run Docker.
Optional: pull the MCP Docker image. The image will be pulled automatically when you start the AI agent. To ensure it is available ahead of time or avoid a delay during the initial startup, pull it manually:
```
docker pull woodpeckerco/woodpecker-mcp-server
```

Configure the AI agent

Claude Desktop

The following steps are specific to Claude Desktop.

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

Add the 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}"
      }
    }
  }
}

Restart Claude Desktop if it was running.
Verify and test the connection.

Look for the Woodpecker tools in the interface, or ask the AI agent:
```
"What Woodpecker tools do you have access to?"
"List my Woodpecker campaigns"
```

Other AI agents

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

Troubleshooting

Docker server not connecting

Symptoms: AI agent can't access Woodpecker tools

Check if the Docker container is running: docker ps
Try the absolute Docker path (for example, /usr/local/bin/docker) in the MCP server configuration
Test the API key by making a direct API call to Woodpecker

Invalid API credentials

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

Regenerate the API key in the Woodpecker add-ons section
Update the environment variable with the new key
Restart the AI agent application

Tools not available

Symptoms: AI agent doesn't see Woodpecker functions

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

Start Docker​

Configure the AI agent​

Claude Desktop​

Other AI agents​

Troubleshooting​