Skip to main content

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.

The hosted connection is currently supported only in Claude. 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.

  1. In Claude, open Settings and select Connectors.

  2. Select Add, then Add custom connector.

  3. Enter a name for the connector, for example Woodpecker.

  4. Enter the following remote MCP server URL:

    https://api.woodpecker.co/mcp/v1

    Leave the OAuth Client ID and OAuth Client Secret fields empty.

    Claude custom connector setup screen with the Woodpecker name and remote MCP server URL entered

  5. Add the connector, then select Connect.

  6. Sign in to your Woodpecker account when prompted.

  7. Review the requested access and select Allow.

    Woodpecker authorization screen listing the permissions requested by Claude

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"

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

An Agency client account cannot be selected

Symptoms: You connected an Agency account but cannot access or switch to one of its client accounts.

  • The hosted Woodpecker MCP server does not currently support selecting client accounts managed under an Agency account. To work with Agency client accounts, run the MCP server locally with Docker and authenticate it with the appropriate Woodpecker API key.