Provides read-only, multi-instance Jenkins access for AI assistants, enabling inspection of jobs, builds, stages, logs, test failures, artifacts, workspaces, nodes, queues, job configurations, config history, SCM usage, and known-issue matching against a local team knowledge base without modifying Jenkins.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jenkins MCP Server why did the latest build of payments-service fail?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only, multi-instance Jenkins access for AI assistants: VS Code GitHub Copilot (Agent mode) at work, Claude Code for local testing, or any other MCP client. Large build logs are analysed on the server; the model only receives small, relevant excerpts. A team knowledge base remembers solved problems, so the next analysis starts from what the team already knows.
Company use | Local testing / development | |
Who | everyone who analyses builds at work | developers of this server |
Platform | Windows | macOS or Windows |
AI client | VS Code GitHub Copilot (Agent mode) | Claude Code (macOS) or VS Code Copilot (Windows) |
Jenkins | your company Jenkins | a test Jenkins in Docker (or any reachable one) |
Setup |
|
|
Step-by-step guide | ||
Client config |
| macOS: registered by the script ( |
The server code is the same in both cases. Day-to-day usage: docs/USER_GUIDE.md.
Related MCP server: Debugging MCP Server
The server cannot change anything in Jenkins:
Its HTTP session (ReadOnlySession in src/jenkins_mcp/client.py) refuses every method except
GET and HEAD before a request leaves the process. A tool that tried to trigger, stop, delete or
configure something would fail with "this MCP server is read-only".
Credentials are only sent to the configured Jenkins URLs; URLs of other hosts are refused.
Every tool that talks to Jenkins is marked readOnlyHint for the AI client. Only draft_kb_entry and
propose_kb_update write: one new local file in knowledge/drafts/ each time (never overwrites, never
Jenkins), so they are honestly marked as local writes.
The only other local writes are the log cache (~/.cache/jenkins-mcp, owner-only permissions).
Tested: offline (no non-GET request is ever sent, POST/PUT/PATCH/DELETE blocked) and live against a real Jenkins (all build numbers unchanged after running every tool).
jenkins-mcp/
├── src/jenkins_mcp/ SERVER CODE (same on Windows and macOS, installed with pip)
├── config/ YOUR SETTINGS: *.example templates committed; your yaml/.env are git-ignored
├── knowledge/ TEAM DATA: known issues (Markdown); may also live in its own repo
├── docs/USER_GUIDE.md how to use it day to day
│
├── setup/windows/ COMPANY: Windows + VS Code Copilot
│ ├── setup.ps1 install script (-Dev: + test tools, for developers)
│ └── README.md step-by-step guide
├── .vscode/ VS Code: mcp.json = Copilot server (generated, git-ignored; template mcp.example.json),
│ settings.json = pytest
│
└── tests/ LOCAL TESTING / DEVELOPMENT (never installed)
├── README.md step-by-step guide: macOS + Claude Code, Windows + VS Code
├── macos/setup.sh macOS: install + Claude Code registration + offline tests
├── test_*.py offline tests (pytest, fake Jenkins)
├── fixtures/ sample log + example knowledge base for the tests
└── live/ real Jenkins in Docker + live check of every tool (run_live.sh / run_live.ps1)Source package:
src/jenkins_mcp/
├── app.py FastMCP object, server instructions, shared parameter types
├── main.py imports tools + prompts, run() (command: jenkins-mcp)
├── vscode_config.py writes .vscode/mcp.json (token prompts per instance), called by setup.ps1
├── xmlutil.py Jenkins XML 1.1 parsing
├── settings.py paths (JENKINS_MCP_HOME), env tunables
├── config.py config/jenkins_instances.yaml + config/.env -> Settings, validation, instance lookup
├── client.py ReadOnlySession (GET/HEAD only), Instance
├── targets.py job/build/URL resolution
├── text.py secret masking, output budget, formatting
├── rules/ built-in error/ignore/noise rules (YAML)
├── logs/ download + cache, cleaning, stage detection, error grouping
├── kb/ knowledge base: load entries, match against logs
├── tools/ MCP tools: instances, jobs, builds, logs, artifacts, infra, knowledge
└── prompts.py analyse_build, document_sessionFiles (templates in config/, your copies are git-ignored):
File | Content |
| Jenkins instances, TLS, log rules, knowledge base folder (template: |
| Credentials, one pair per instance (template: |
Environment variables (set them in config/.env, in the MCP client config, or in the shell):
Variable | Default | Purpose |
| - | Credentials of instance |
| nearest parent of the working dir with | Project folder with |
|
| Instance file |
|
| Knowledge base folder (e.g. a private team repo) |
|
| Log cache (contains raw console logs) |
|
| Cache size limit |
|
| Larger logs keep the first 20 % and the end |
|
| Hard size limit of one tool answer |
|
| Job lists ( |
|
| Server log level (stderr) |
After editing the yaml or .env, call list_instances(reload_config=true); no restart is needed.
Config problems are reported by list_instances under config_errors.
Use a dedicated Jenkins user with read permissions only (Overall/Read, Job/Read) for the API token. The server never writes to Jenkins, but a read-only account limits the damage if a token leaks.
Tool | Purpose |
| instances, token source, connection check (version, user/groups, admin rights, quiet-down), config errors, knowledge base state; |
| recursive job list with status/folder/name filter; failing jobs show the last green build |
| red/yellow jobs in the last N hours across all instances, with the last green build |
| every build in the last N hours across all instances: result, culprits, long-running builds |
| job details, permalinks, recent builds, parameters, children |
| which jobs build a repository (or load a Shared Library), across instances; any URL spelling |
| start here: result, params, agent, culprits, downstream builds, pending input, stages, failed stage, known issues, root-cause candidates, tail |
| errors and tail of one stage (default: failed stage); |
| what a running build waits for ( |
| de-duplicated error groups, annotated by the knowledge base |
| regex search with context / line windows |
| failed JUnit cases incl. how long they fail |
| what actually ran: Jenkinsfile source, git checkouts, Shared Library versions (hint on LF-version mismatch), replay, slowest steps; |
| good vs bad: agent, params, stages, commits (Jenkinsfile/groovy changes flagged), new errors, errors also in good build, env.log diff; pick builds by node ( |
| config.xml as a summary: SCM, Jenkinsfile path, parameters, triggers, retention, label, build steps, Config File Provider files, credential IDs; |
| content of a Config File Provider file (settings.xml...), secrets masked |
| who changed the job config and when (Job Config History plugin); semantic + XML diff of two versions or against the live config |
| artifact list (sizes, download URL), text artifacts (UTF-8, UTF-16, cp1252), secrets masked |
| artifacts of two builds: added/removed, changed (fingerprint, size, bytes); diff of one text artifact, checksum of a binary |
| files that were not archived, from the job / Pipeline node-block workspace (current state on the agent) |
| agents (labels, disk, memory, offline reason, clock) and queue |
| one node: labels, which build runs on which executor, Java version, config.xml (remote root, launcher, node env vars masked, tool locations) |
| match a build or a pasted error text against the knowledge base |
| read / list entries, with how often each matched since the server started |
| write a new local draft in |
| propose an update of an existing entry (new build, extra regexes) as a new draft next to it (local write) |
| errors across the newest builds of a job: regression ("new since #N") vs. also in green builds |
Prompts: analyse_build, document_session, morning_report (Copilot: type / and pick mcp.jenkins...;
Claude Code: /mcp__jenkins__analyse_build).
All tools are read-only towards Jenkins; see Read-only guarantee.
Analyse a build. get_build_summary shows known_issues if an entry matches.
When the cause is found and confirmed, run the prompt document_session (or ask the agent).
It checks for duplicates and calls draft_kb_entry, or propose_kb_update when an entry already exists.
recurring_errors finds red-herring candidates (errors that also occur in green builds).
Review the draft in knowledge/drafts/, move it to knowledge/, commit it to your team's private
knowledge repo. The server picks up file changes automatically.
Company knowledge does not belong in this public repository: .gitignore excludes knowledge/KB-*.md and
drafts. Keep entries in a private repo and point JENKINS_MCP_KB_DIR (or knowledge.dir) at its checkout.
Format and field reference: knowledge/README.md. Start new entries from knowledge/TEMPLATE.md.
See tests/README.md. Adding a tool: write a function with
@mcp.tool(annotations=READ_ONLY) in a module under src/jenkins_mcp/tools/ (for a new module also import
it in tools/__init__.py), and add a test to tests/test_tools.py.
Multibranch branch names containing / are addressed with %2F (as list_jobs shows them).
Stage line ranges come from console markers; output of parallel branches can interleave
(get_stage_log exact=true reads the stage step by step from wfapi instead).
Builds still running are not cached on disk; their log is fetched incrementally (only the new part).
Downstream builds are recognised from the console line Starting building: <display name> #N. If a job
has a custom display name, it cannot be resolved by that name, and the summary says so.
Logs larger than JENKINS_MCP_MAX_LOG_MB keep the first 20 % and the end.
Log content is untrusted: a log line can contain text that looks like an instruction. The server cannot change Jenkins, so such text cannot trigger actions through it.
See SECURITY.md for the threat model and how to report a vulnerability.
MIT © 2026 Telman Huseynli
Release 1.1.0: the live Docker test (Jenkins 2.580.1) and a manual Windows / VS Code Copilot run against real
instances passed. Set the package status back to 5 - Production/Stable, turn Unreleased in CHANGELOG.md into
1.1.0, tag v1.1.0 and publish a GitHub release.
Replace the module-level singletons (config, knowledge base cache, log LRU, job tree cache) with one application
context object, and pass log rules into logs/ instead of reading the global config there.
CI pipeline on Windows: ruff, mypy, pytest.
Read-only plugin tools: installed plugins and versions, plugins with problems (missing dependencies), available
updates. /pluginManager/api/json?depth=1 usually needs Overall/SystemRead or Administer: check it with a normal
user's token first; without that permission the tools would only return 403.
More read tools: views, node env/PATH (system info, needs admin), Jenkinsfile and JCasC history from Git (Bitbucket).
Optional HTTP transport for one shared team server (needs authentication / a gateway).
Human-in-the-loop write actions (not implemented): plan_* tool -> one-time token ->
human confirms -> execute_plan with a separate service account and an allow-list.
This server cannot be deployed
Structured knowledge base for AI agent solutions. Search, explore, and retrieve build logs.
Your AI's work, reviewed by your team, remembered - shared artifacts with review, plus team memory.
Gives your AI assistant persistent memory and intelligence about your work patterns.
One memory for every AI tool on your team. Facts show who checked them and when.
