# Woodpecker CI MCP MCP > Woodpecker CI lets you manage your entire continuous integration and deployment stack directly from chat. Trigger builds, monitor agent health, update repository settings, and handle secrets without opening a dashboard or writing a single command line. It gives developers and ops engineers full control over their build pipelines using natural language. ## Overview - **Category:** ship-it - **Price:** Free - **Tags:** ci-cd, pipelines, automation, deployment, monitoring, build-management ## Description You can automate all the complex steps involved in building and deploying code through your AI client. Instead of jumping between dashboards to check agent status or manually triggering builds, you talk to this MCP. You tell it which pipeline needs running for a specific repo, and it handles the rest. It lets you manage secrets—whether they’re global organization settings or just specific repository keys—and keeps tabs on everything. Need to know if an agent is online? Ask. Want to check what configuration files a build used? It finds them. You can even update repo settings, like repairing webhooks that break. Because Vinkius handles all credentials using a zero-trust proxy, your sensitive tokens never sit on disk—it’s safe. This capability lets you orchestrate entire DevOps workflows across multiple platforms. For instance, you can chain this MCP with a messaging tool to automatically post success status updates once the build finishes. The whole thing runs through Vinkius AI Analytics, so you always see exactly which tools were called and how much of your budget was used. ## Tools ### activate_repo Marks a repository as active on the server. ### cancel_pipeline Stops a pipeline that is currently running. ### chown_repo Changes the owner of a repository to your current user account. ### create_agent Adds and configures a brand new build agent for the system. ### create_global_secret Creates a secret accessible across all organizations on the server. ### create_repo_secret Adds a sensitive key specific to one repository. ### delete_agent Removes an agent from the system completely. ### delete_pipeline Deletes a previously run pipeline record. ### delete_repo Deactivates or permanently deletes an entire repository. ### get_agent Fetches specific details about a single build agent. ### get_healthz Checks the overall operational health of the CI server instance. ### get_metrics Retrieves detailed performance metrics from Prometheus for monitoring purposes. ### get_org_permissions Lists what permissions a user has within an organization. ### get_pipeline_config Fetches the actual configuration files used by a given pipeline. ### get_pipeline Retrieves general details about a specific pipeline run. ### get_repo Gets general metadata and details for any repository. ### get_user Identifies the user account currently authenticated to the system. ### get_version Reports the current version number of the Woodpecker server software. ### list_agent_tasks Shows all tasks that are currently assigned to a specific agent. ### list_agents Lists every available build agent connected to the server. ### list_global_secrets Displays all secrets created at the global administrative level. ### list_org_agents Lists agents that belong only to a specific organization. ### list_org_secrets Shows all secrets created at the organization level. ### list_orgs Retrieves a list of every organizational container on the server. ### list_pipelines Lists all completed pipeline runs for a specific repository. ### list_repo_secrets Displays all secrets that are attached to one particular repository. ### list_repos Lists every single repository available on the entire server. ### list_users Displays a list of all user accounts configured in the system (Admin only). ### lookup_repo Finds and retrieves details for a repository using its full name or slug. ### repair_repo Fixes broken webhooks for an existing repository so it can trigger builds again. ### restart_pipeline Forces a restart of a pipeline that previously ran. ### trigger_pipeline Manually starts a new build process for a repository. ### update_agent Modifies the configuration of an existing build agent. ### update_repo Updates general settings and parameters for a specific repository. ## Prompt Examples **Prompt:** ``` List all Woodpecker agents and show their current status. ``` **Response:** ``` I've retrieved the agent list. You have 3 agents: 'docker-runner-01' (Online), 'k8s-agent-alpha' (Online), and 'legacy-local' (Offline). Would you like to see the tasks assigned to 'docker-runner-01'? ``` **Prompt:** ``` Find the repository 'vinkius/mcp-server' and trigger a new pipeline. ``` **Response:** ``` Found it (ID: 42). I have triggered a new pipeline for 'vinkius/mcp-server'. The new pipeline is #154. You can monitor its progress or I can notify you when it finishes. ``` **Prompt:** ``` Show me the last 5 pipelines for repository ID 42. ``` **Response:** ``` Here are the 5 most recent pipelines for repo 42: #153 (Success), #152 (Failure), #151 (Success), #150 (Success), and #149 (Cancelled). Pipeline #152 failed at the 'test' step. Would you like to see the config for that build? ``` ## Capabilities ### Control pipelines Trigger manual builds, restart failed processes, or cancel running jobs for any code repository. ### Manage agents View all connected build agents, check their operational health, and create or delete them as needed. ### Handle secrets Create, list, and manage sensitive configuration keys at the global, organization, or repository level. ### Inspect infrastructure state Retrieve detailed system metrics, server versions, and current user permissions to audit the environment. ### Manage repositories Activate new codebases, update their settings, or repair broken webhooks directly through conversation. ## Use Cases ### A build fails, and I need to know why. The dev noticed a pipeline failure. Instead of digging through logs, they ask their agent to use `get_pipeline` for the last run and then use `list_pipelines` to see the history. They find out the build failed because the repository needed its webhooks repaired using `repair_repo`. ### We need a new dedicated testing environment. The ops team needs more capacity. They use their agent to first check if they can create resources (`create_agent`) and then run it for the specific repo using `activate_repo` before running test builds via `trigger_pipeline`. ### I need to update a deployment secret. A critical API key expires. The developer uses their agent to find all relevant secrets with `list_global_secrets`, updates the required credential using `create_repo_secret`, and ensures it’s properly linked via `update_repo`. ### The build system seems slow or unstable. The SRE needs to check performance. They use `get_metrics` for detailed Prometheus data, then use `list_users` and `get_user` to confirm who has admin access and what their permissions are via `get_org_permissions`. ## Benefits - You get immediate visibility into infrastructure health. Use `get_healthz` or `list_agents` to quickly check if your build runners are online without opening a dedicated monitoring dashboard. - Managing credentials is painless. You can use `create_global_secret` or `create_repo_secret` to store sensitive keys, and the process is safe because Vinkius handles credentials using a zero-trust proxy; your tokens never sit on disk. - Debugging pipelines is faster than ever. Instead of guessing what went wrong, you can ask for the configuration files with `get_pipeline_config` or check past runs using `list_pipelines` to see exactly where it failed. - Repository maintenance is simple. If a webhook breaks, running `repair_repo` fixes it instantly from your conversation, letting you get back to coding without manual intervention. - You can automate the entire lifecycle. You don't just trigger builds; you use tools like `trigger_pipeline` and then follow up with `get_user` details to log who initiated the deployment. ## How It Works The bottom line is you manage complex infrastructure using simple commands in chat. 1. Provide your Woodpecker Server URL and the necessary personal access token. 2. Connect this MCP to your preferred AI client (Claude, Cursor, etc.). 3. Tell your agent exactly what needs doing—for example: 'Check the health of all agents' or 'Trigger a pipeline for repo X'. ## Frequently Asked Questions **How do I trigger a new build with the Woodpecker CI MCP?** You use the `trigger_pipeline` tool. Just tell your agent which repository and what kind of manual run you need, and it starts the process immediately. **What if I want to stop a build that's running right now? Use cancel_pipeline.** To halt an active job, use `cancel_pipeline`. You just reference the pipeline ID or name, and your agent sends the cancellation signal to the server. **Can I update my repository settings using the Woodpecker CI MCP?** Yes, you can use `update_repo` to adjust general repo parameters. You'll need to provide the specific changes and the ID of the repository you want to modify. **How do I check if my webhooks are broken? Use repair_repo.** If a build isn't triggering automatically, run `repair_repo`. This tool fixes any broken webhook connections for that repo, getting your CI process running again fast. **What is the difference between list_agents and get_agent?** Use `list_agents` to see every agent connected to the system. If you need detailed status or specific info on just one, run `get_agent`. **How do I check if my Woodpecker CI server is actually operational using get_healthz?** It provides an immediate status report on the entire CI infrastructure. This simple call confirms if the whole system is up and running smoothly, helping you rule out service outages before triggering any builds. **I'm setting up a new project; how do I make sure my repository is ready to build using activate_repo?** Using activate_repo makes the repository fully visible and ready for CI processes. Sometimes, repos need explicit activation before agents can properly run builds or hooks against them. **How do I view all organization-level secrets with list_org_secrets?** This tool shows credentials set up for the entire organization. It lets you verify shared keys and tokens that multiple agents need to access, keeping your critical configurations centralized. **Can I trigger a new pipeline build for a specific repository?** Yes. Use the `trigger_pipeline` tool by providing the repository ID. You can also specify a branch or commit if needed to start a new execution immediately. **How do I check if my build agents are online and healthy?** You can use `list_agents` to see all connected agents and their status. For more detail on a specific agent, use `get_agent` or `list_agent_tasks` to see what it's currently working on. **Is it possible to manage environment secrets through this agent?** Yes, the server includes tools like `create_repo_secret` and `list_repo_secrets` to manage sensitive variables at the repository level, as well as global and organization-level secret tools.