Woodpecker CI MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Woodpecker CI. Debug pipeline failures, analyze build logs, and troubleshoot CI/CD configurations 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"
    }
  }
}

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

Tool	Description	Parameters
search_repository	Find repository by name	name (e.g., "owner/repo")
list_repositories	List all repositories	Optional: page, perPage, active, trusted
list_pipelines	List repository pipelines	repoId, optional: before, after, pagination
get_pipeline	Get detailed pipeline info	repoId, number
get_pipeline_config	View pipeline configuration	repoId, number
get_step_logs	Get logs for debugging	repoId, number, stepId

AI Prompts

Prompt	Description
review-pipeline-error	Systematic analysis of pipeline failures

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! 🚀🤖