woodpecker-mcp by j04n-f - MCP Server

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

Install dependencies
```
bun install
```

Run the server

# Development with inspector
bun run dev

Set environment variables using Inspector

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

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

Go to your Woodpecker CI instance
Click your profile icon → "CLI & API"
Copy the personal access token
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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Follow the coding standards: bun run lint
Commit changes: git commit -m 'feat: add amazing feature'
Submit a Pull Request

License

MIT License - see for details.

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