@devpuccino/mcp-woodpecker

v1.1.2

Published

a month ago

Model Context Protocol (MCP) server for Woodpecker CI 3.13.0+ with comprehensive API tool support for pipeline management, secrets, registries, and more

Downloads

0High
0Medium
0Low

devpuccino

mcp model-context-protocol woodpecker-ci ci-cd automation api pipeline devops

MCP Woodpecker Server

A comprehensive Model Context Protocol (MCP) server for seamlessly integrating Woodpecker CI with AI-powered tools. This server provides 41+ tools to manage repositories, pipelines, secrets, registries, crons, and organization settings programmatically. Fully compatible with Woodpecker CI 3.13.0 API.

Perfect for automating CI/CD workflows, integrating with Claude AI, or building custom Woodpecker management tools.

🔄 Compatibility

| Component | Version | Notes | |-----------|---------|-------| | mcp-woodpecker | 1.1.2+ | MCP Server implementation | | Woodpecker CI API | 3.13.0+ | Tested against Woodpecker CI v3.13.0 (January 2026) | | Node.js | 18.0.0+ | Minimum required version | | MCP SDK | ^1.27.1 | Model Context Protocol SDK |

This server is compatible with Woodpecker CI 3.13.0 and later. The implementation follows the official Woodpecker API specification with support for modern endpoints and features.

📝 Changelog

v1.1.2 (2026-03-21) - Bugfix Release

Fixed: get_server_info tool removed — /version endpoint returns HTML on live deployments
Fixed: get_pipeline_logs now uses correct path /repos/{id}/logs/{number}/{stepID} (HTML was from old wrong path)
Fixed: All org secret tools (list_org_secrets, get_org_secret, etc.) now use numeric orgId instead of org name — resolves 400 Bad Request
Added: lookup_organization tool to resolve org name → numeric ID before secret operations
Tested: All 47 unit tests passing

v1.1.1 (2026-03-21) - Bugfix Release

Fixed: cancelPipeline now calls POST .../cancel instead of DELETE (which deletes the pipeline permanently)
Fixed: getPipelineStatus now maps to GET /repos/{id}/pipelines/{number} — no separate /status endpoint exists in the API
Fixed: getStepLogs path corrected to /repos/{id}/logs/{number}/{stepID} per API spec
Fixed: deletePipelineLogs path corrected to /repos/{id}/logs/{number} per API spec
Fixed: activateRepository now uses POST /repos?forge_remote_id=... (query param, not path param)
Fixed: Cron create/update now sends schedule field instead of expr to match API schema
Fixed: list_org_secrets and all org secret tools now require numeric orgId (not org name) — matches GET /orgs/{org_id}/secrets API spec
Added: lookup_organization tool — resolves org name → numeric ID via GET /orgs/lookup/{org_full_name}
Removed: get_server_info tool — /version endpoint returns HTML on this deployment (no reliable alternative)
Tested: All 47 unit tests updated and passing

v1.1.0 (2026-03-21)

Added: updateRegistry() method for updating registry credentials
Updated: Version documentation and compatibility matrix
Tested: Comprehensive registry CRUD operations

✨ Features

Repository Management - List, get, activate, update, and delete repositories
Pipeline Management - Trigger, cancel, monitor pipelines with detailed logs and status
Secrets Management - Create and manage repository and organization-level secrets securely
Registry Configuration - Manage Docker registry credentials for authenticated builds
Cron Jobs - Schedule and manage automated pipeline executions with flexible expressions
User & Server Info - Get authenticated user details and server information
Full Type Safety - Built with TypeScript for reliable development

🚀 Quick Start

Installation

npm install -g mcp-woodpecker

Or as a project dependency:

npm install mcp-woodpecker

Prerequisites

Node.js 18.0.0 or higher
Woodpecker CI instance running and accessible
API Token from your Woodpecker instance (Personal Access Token)

Basic Setup

Get your Woodpecker API token:
- Navigate to your Woodpecker instance (e.g., https://woodpecker.example.com/)
- Go to Settings → Personal Access Tokens
- Create a new token with appropriate permissions
Set environment variables:

export WOODPECKER_URL=https://woodpecker.example.com/
export WOODPECKER_API_KEY=your_api_token_here

Run the MCP server:

mcp-woodpecker

Or in development mode with hot reload:

npm install --save-dev mcp-woodpecker
npm run dev

Using with npx (No Installation)

Run the server directly without installing it globally:

export WOODPECKER_URL=https://woodpecker.example.com/
export WOODPECKER_API_KEY=your_api_token_here
npx mcp-woodpecker

This is useful for testing, CI/CD pipelines, or ephemeral environments.

Using with Claude AI

Add to your .claude/config.json:

{
  "servers": {
    "woodpecker": {
      "command": "npx",
      "args":["-y","@devpuccino/mcp-woodpecker"],
      "env": {
        "WOODPECKER_URL": "https://woodpecker.example.com/",
        "WOODPECKER_API_KEY": "your_api_token"
      }
    }
  }
}

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | WOODPECKER_URL | Base URL of your Woodpecker instance | https://woodpecker.example.com | | WOODPECKER_API_KEY | Personal access token for API authentication | eyJ... |

Available Tools

Repository Tools

list_repositories - List all accessible repositories
get_repository - Get details of a specific repository
activate_repository - Activate a repository
update_repository - Update repository settings (trusted status, visibility, config path)
delete_repository - Remove a repository from Woodpecker

Pipeline Tools

list_pipelines - List pipelines with optional filtering by branch or status
get_pipeline - Get detailed pipeline information
get_pipeline_status - Get pipeline status badge data
trigger_pipeline - Trigger a new pipeline execution
cancel_pipeline - Cancel a running pipeline
get_pipeline_logs - Retrieve logs from a specific step
delete_pipeline_logs - Clear pipeline logs

Secret Management Tools

Repository Secrets:

list_secrets - List all secrets in a repository
get_secret - Get a specific secret
create_secret - Create a new secret
update_secret - Update an existing secret
delete_secret - Remove a secret

Organization Secrets:

list_org_secrets - List organization-level secrets
get_org_secret - Get a specific org secret
create_org_secret - Create a new org secret
update_org_secret - Update an org secret
delete_org_secret - Remove an org secret

Registry Tools

list_registries - List configured Docker registries
get_registry - Get registry configuration
create_registry - Add a new registry
update_registry - Update registry credentials (new in v1.0.0)
delete_registry - Remove a registry

Cron Job Tools

list_crons - List scheduled cron jobs
get_cron - Get cron job details
create_cron - Create a new scheduled job
update_cron - Update cron configuration
delete_cron - Remove a cron job

Server Tools

get_current_user - Get authenticated user information
get_server_info - Get Woodpecker server version and info

CI/CD Pipeline

This project includes a .woodpecker.yml configuration that provides:

Build & Test Stages

Feature Builds: Manual trigger for testing features
Development Builds: Automatic on push to develop branch
Production Builds: Automatic on version tags (v*)

Docker Builds

Multi-stage Docker builds with registry authentication
Separate images for test, dev, and production environments

Deployment Stages

Test Deployment: Manual deployment of test image
Development Deployment: Automatic deployment on develop push
Production Deployment: Automatic deployment on version tag + npm publish

npm Publishing

Production releases are automatically published to the npm registry on version tags.

Required Secrets

For CI/CD to work, configure these secrets in your Woodpecker instance:

| Secret | Description | |--------|-------------| | REGISTRY_USERNAME | Docker registry username | | REGISTRY_PASSWORD | Docker registry password/token | | NPM_TOKEN | npm registry authentication token | | WOODPECKER_URL_TEST | Test Woodpecker instance URL | | WOODPECKER_API_KEY_TEST | Test instance API key | | WOODPECKER_URL_DEV | Development Woodpecker instance URL | | WOODPECKER_API_KEY_DEV | Development instance API key | | WOODPECKER_URL | Production Woodpecker instance URL | | WOODPECKER_API_KEY | Production instance API key |

Repository Structure

feature/*     → develop (feature development)
develop       → master (testing environment)
master        → production (stable releases)
v*            → npm + docker registry (tagged releases)

🐳 Docker Usage

Build Docker Image

docker build -t mcp-woodpecker:latest .

Run in Docker

docker run -d \
  -e WOODPECKER_URL=https://woodpecker.example.com \
  -e WOODPECKER_API_KEY=your_token \
  --name mcp-woodpecker \
  mcp-woodpecker:latest

Docker Compose

version: '3.8'
services:
  mcp-woodpecker:
    build: .
    environment:
      WOODPECKER_URL: https://woodpecker.example.com
      WOODPECKER_API_KEY: ${WOODPECKER_API_KEY}
    restart: unless-stopped

📝 Publishing to npm

This package is published to npm as @devpuccino/mcp-woodpecker.

Version Management

Versions follow Semantic Versioning:

MAJOR: Breaking API changes
MINOR: New features (backward compatible)
PATCH: Bug fixes and patches

Release Process

Update version in package.json:

npm version major|minor|patch

Push changes:

git push origin master --tags

Publish to npm:

npm publish

The Woodpecker CI pipeline automatically publishes to npm on version tags.

🤝 Contributing

Contributions are welcome! See CONTRIBUTE.md for detailed guidelines on:

Setting up your development environment
Adding new tools to the MCP server
Code quality standards
Pull request process
Commit message conventions

For bug reports and feature requests, please open an issue.

🐛 Troubleshooting

Authentication Error

Error: Woodpecker API error: 401 Unauthorized

Verify WOODPECKER_API_KEY is correct
Check token hasn't expired
Ensure user has API access permissions

Connection Refused

Error: connect ECONNREFUSED

Verify WOODPECKER_URL is accessible
Check network connectivity
Ensure Woodpecker instance is running

Module Not Found

Error: Cannot find module '@modelcontextprotocol/sdk'

Run npm install to install dependencies
Clear npm cache: npm cache clean --force
Delete node_modules and reinstall: rm -rf node_modules && npm install

📄 License

See LICENSE file for details.

🔗 Resources

Woodpecker CI Documentation - Official Woodpecker documentation
MCP Specification - Model Context Protocol details
Woodpecker API Reference - REST API documentation
npm Package - npm registry entry
GitHub Repository - Source code

🙋 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
npm Profile: @devpuccino