Woodpecker CI MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Woodpecker CI. Debug pipeline failures, analyze build logs, troubleshoot CI/CD configurations, and act on pipelines and repositories (trigger, restart, cancel, approve/decline, activate, update settings) with AI assistance.

MCP Client Setup

Add to your MCP client configuration:

Standalone Binary

{
  "woodpecker-ci": {
    "command": "woodpecker-mcp",
    "env": {
      "WOODPECKER_TOKEN": "your-token-here",
      "WOODPECKER_URL": "https://your-woodpecker-instance.com"
    }
  }
}

Docker

{
  "woodpecker-ci": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e", "WOODPECKER_TOKEN",
      "-e", "WOODPECKER_URL",
      "ghcr.io/j04n-f/woodpecker-mcp"
    ],
    "env": {
      "WOODPECKER_TOKEN": "your-token-here",
      "WOODPECKER_URL": "https://your-woodpecker-instance.com"
    }
  }
}

Related MCP server: Woodpecker CI Pipeline Analyzer

Quick Start

1. Install dependencies

   bun install

2. Run the server

   # Development with inspector
   bun run dev

3. Set environment variables using Inspector

   WOODPECKER_URL="https://your-woodpecker-instance.com"
   WOODPECKER_TOKEN="your-personal-access-token"

4. Start development environment

   # Start Gitea + Woodpecker CI for testing
   ./scripts/setup-environment.sh
   
   # Access services:
   # - Gitea: http://localhost:3000 (woodpecker/woodpecker123)
   # - Woodpecker: http://localhost:8000

Configuration

Getting Your Woodpecker Token

1. Go to your Woodpecker CI instance

2. Click your profile icon → "CLI & API"

3. Copy the personal access token

4. Set it as WOODPECKER_TOKEN

API Reference

AI Prompts

Development

Available Commands

# Development
bun run dev          # Start with inspector
bun run build        # Build production binary

# Code Quality
bun run lint         # Check code style
bun run lint:fix     # Auto-fix issues

Local Testing Environment

The included Docker Compose setup provides:

• Gitea: Git forge with webhooks

• Woodpecker CI: Complete CI/CD environment

• Test repository: Sample project with pipeline configuration

Perfect for testing MCP integration without external dependencies.

Examples

Debug a Failed Pipeline

AI: Can you check why pipeline #42 failed for repository owner/project?

Analyze Build Performance

AI: Show me the recent pipeline performance for my main repository and identify any bottlenecks.

Configuration Review

AI: Review the pipeline configuration for repository owner/project and suggest improvements.

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Follow the coding standards: bun run lint

4. Commit changes: git commit -m 'feat: add amazing feature'

5. Submit a Pull Request

License

MIT License - see LICENSE for details.

Ready to supercharge your Woodpecker CI workflows with AI assistance! 🚀🤖