Connect Claude to the Woodpecker MCP server

Connect Woodpecker to Claude in just a few steps - no local server or API key required. Once connected, you can chat with Claude to manage your campaigns wherever you work: on the web, in the desktop or mobile app, or in Claude Code.

Connecting Claude

Choose whether you want to connect through Claude or Claude Code.

Claude
Claude Code

Setup steps vary by Claude plan. On Team and Enterprise plans, an Owner must first add the connector for the organization. See Claude's custom connector documentation for the current plan-specific instructions.

In Claude, open Settings and select Connectors.
Select Add, then Add custom connector.
Enter a name for the connector, for example Woodpecker.
Enter the following remote MCP server URL:
```
https://api.woodpecker.co/mcp/v1
```
Leave the OAuth Client ID and OAuth Client Secret fields empty.
Add the connector, then select Connect.
Sign in to your Woodpecker account when prompted.
Review the requested access and select Allow.

After authorization, the connector settings show the available Woodpecker tools and let you control whether Claude can use each tool automatically, with approval or not at all.

Claude connector settings showing Woodpecker tools and approval controls

To verify the connection, ask Claude:

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

Add the Woodpecker remote MCP server using the Claude Code CLI:

claude mcp add --transport http woodpecker https://api.woodpecker.co/mcp/v1

Then authenticate the connection:

claude mcp login woodpecker

To verify that the server is connected, run:

claude mcp list

You can also check the connection from within a Claude Code session by running:

/mcp

See the official Claude Code MCP documentation for additional configuration options.

Troubleshoot the Claude connection

The connector is not available

Symptoms: You cannot find or add the Woodpecker connector

On a Team or Enterprise plan, ask an Owner to add the custom connector to the organization
After the Owner adds it, open Settings → Connectors, find Woodpecker and select Connect

Authorization was not completed

Symptoms: Woodpecker remains disconnected in Claude

Open Settings → Connectors and select the Woodpecker connector
Select Connect, sign in to the intended Woodpecker account and complete the authorization by selecting Allow

The connector was disconnected after a period of inactivity

Symptoms: A previously working Woodpecker connector is disconnected or Claude asks you to authorize it again

The authorization may expire if the connector has not been used for an extended period. When prompted by Claude, sign in to Woodpecker and authorize the connection again.
You can also reconnect it manually from Settings → Connectors.
In Claude Code, run /mcp and select Woodpecker

Tools are not available in a conversation

Symptoms: Claude is connected to Woodpecker but cannot use its tools

Enable the Woodpecker connector for the current conversation from the + menu
Open the connector settings and make sure the required tools are not disabled
If a tool is set to Needs approval, approve its use when Claude requests it

Connecting Claude​

Troubleshoot the Claude connection​