Skip to content

Tools

jenkins-mcp registers 22 tools, grouped into 6 toolsets. Each toolset can be individually enabled/disabled with JENKINS_TOOLSETS (see Configuration); a w in the R/W column marks a mutating tool, suppressed entirely when JENKINS_READONLY=true.

Paging and size limits

Every list_* tool takes limit (default 50, maximum 200) and offset, and returns count, offset and hasMore. When hasMore is true, call again with offset set to offset + count. Paging is done server-side with Jenkins' own tree range syntax, so a controller with thousands of jobs never sends them all.

Tools that return raw text — jenkins_get_build_console, jenkins_get_stage_log, jenkins_get_artifact, jenkins_get_job_config — cap their output at 64 KiB and set truncated when they cut it, so a multi-megabyte console log can't exhaust the model's context in a single call.

jenkins_get_build_console also takes tail: true, which returns the END of the log instead of the beginning — what you want when diagnosing a failure. Its start field reports the offset the returned text begins at, and truncated is true whenever the response is not the complete log, including when a tail read skipped everything before start.

jobs

Tool R/W Description
jenkins_list_jobs r List jobs at the top level or within a folder.
jenkins_get_job r Get a job's description, health, buildability, last-build pointers, and parameters.
jenkins_search_jobs r Find jobs by name substring, searching inside folders (depth 3 by default, max 5).
jenkins_get_job_config r Get a job's raw config.xml — its full definition.

Folders appear in jenkins_list_jobs as entries with isFolder: true; descend by calling again with folder set to that entry's fullName.

builds

Tool R/W Description
jenkins_get_build r Get a build's status, timing, parameters, causes, change set, and test summary.
jenkins_trigger_build w Enqueue a new build, optionally with parameters.
jenkins_get_build_console r Read a build's console log, paginated by byte offset.
jenkins_list_artifacts r List the files a build archived.
jenkins_get_artifact r Read one archived artifact's contents.
jenkins_get_test_results r Get a build's test results, listing failures with error details.
jenkins_get_build_stages r List a Pipeline build's stages, statuses and failure reason; failedStage names the one to read.
jenkins_get_stage_log r Read one Pipeline stage's output by step, instead of paging the whole console.
jenkins_stop_build w Abort a running build.

build accepts a build number or any Jenkins permalink (lastBuild, lastSuccessfulBuild, lastFailedBuild, lastStableBuild, lastCompletedBuild, lastUnsuccessfulBuild, lastUnstableBuild, firstBuild). jenkins_get_test_results returns hasResults: false rather than an error for a job that publishes no test report.

jenkins_get_build_stages and jenkins_get_stage_log read the Pipeline Stage View plugin's wfapi endpoints, which Jenkins core does not provide. On an instance without the Pipeline plugins, or for a freestyle build, Jenkins answers wfapi with a 404 and both tools report isPipeline: false rather than failing — so it is always safe to try them first on a failed build.

queue

Tool R/W Description
jenkins_list_queue r List items waiting in the build queue.
jenkins_cancel_queue_item w Cancel a pending queue item.

Use jenkins_cancel_queue_item for a build that has not started yet, and jenkins_stop_build for one that is already running.

nodes

Tool R/W Description
jenkins_list_nodes r List build agents/nodes and their online/idle status.
jenkins_get_node r Get one node's status and per-executor activity.

Pass jenkins_get_node the name field from jenkins_list_nodes, not displayName. For the controller the two differ — Jenkins reports the display name Built-In Node, but only the segment (built-in) resolves under /computer/, and Jenkins exposes it nowhere in the API, so name is reconstructed from the node's _class.

views

Tool R/W Description
jenkins_list_views r List the views configured on the controller.
jenkins_get_view r Get a view's description and the jobs it contains.

plugins

Tool R/W Description
jenkins_list_plugins r List installed plugins with version, enabled/active, and update-available status.
jenkins_system_info r Get Jenkins' version and other system-level status.
jenkins_whoami r Report the identity the configured credentials resolve to.

Input validation

Tool inputs carry real JSON Schema constraints — a pattern on build identifiers, minimums on limit/offset/id, minimum lengths on required path segments — not just descriptions. MCP clients validate a call against the input schema before it reaches the server, so a malformed argument is rejected at the client naming the offending field, rather than surfacing as a confusing Jenkins 404 several layers later.

Adding a tool

Each tool is a concrete Go In/Out struct pair and a handler registered via server.Register — see Architecture. To add one: pick (or create) the right file under internal/jenkinsx/tools/, define the input/output structs, write a handler that calls t.client.Get/PostForm/Text against the Jenkins REST endpoint, and register it in that file's Register* function. No codegen step is involved.

Two rules the test suite enforces:

  • A handler that builds a REST path from a required string must call requireNonEmpty and gain a case in validation_test.go — an empty segment silently collapses the URL onto a different Jenkins resource rather than 404ing.
  • A tree= string and its struct's JSON tags state the same truth twice. Add a field to one and you must add it to the other, and assert in the test that the outgoing tree request contains it — omitempty means a missing field decodes as a zero value with no error at all.

To express a constraint the Go type cannot, implement RefineSchema(*jsonschema.Schema) on the input or output type.