Jenkins Investigator MCP Server

Jenkins Investigator MCP Server

A Model Context Protocol server that helps AI assistants debug failing Jenkins CI jobs efficiently — without blowing through a context window.

Note: This codebase was generated with AI assistance (Claude/Cursor) and reviewed, tested, and validated by humans.

How It Works

Raw Jenkins API responses are enormous. This server acts as a filter: it fetches the verbose data, strips the noise, and returns only what matters — error snippets, commit messages, failing tests.

Tools

Bundles — Start Here

Bundles combine multiple API calls into a single tool invocation, saving tokens and latency.

Individual Tools

Use these for targeted follow-up after a bundle gives you the big picture.

Setup

1. Install dependencies

pip install uv
uv pip install -e .

Or with plain pip:

pip install fastmcp>=3.0.0 requests>=2.31 pydantic>=2.0 python-dotenv>=1.0

2. Configure credentials

cp .env.example .env

Edit .env:

JENKINS_URL=http://your-jenkins:8080
JENKINS_USER=your-username
JENKINS_TOKEN=your-api-token

Your API token can be generated from Jenkins → your user → Configure → API Token.

3. Run the server

python server.py

By default the server starts with Streamable HTTP transport on 0.0.0.0:8000. You'll see the local and network URLs printed on startup.

4. Connect from Cursor / Claude Desktop

HTTP transport (default):

{
  "mcpServers": {
    "jenkins-investigator": {
      "url": "http://192.168.1.42:8000/mcp"
    }
  }
}

Replace the IP with the Network URL printed at server startup.

Stdio transport (set MCP_TRANSPORT=stdio in .env):

{
  "mcpServers": {
    "jenkins-investigator": {
      "command": "python",
      "args": ["/absolute/path/to/jenkins-mcp/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "JENKINS_URL": "http://your-jenkins:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_TOKEN": "your-api-token"
      }
    }
  }
}

Job Names

For simple jobs, use the job name directly: my-job.

For jobs inside folders or multibranch pipelines, use slash-separated paths:

my-org/my-repo/main

The server automatically converts this to the correct Jenkins API path (/job/my-org/job/my-repo/job/main/).

Configuration

Documentation

See Architecture for system design, layer responsibilities, and resilience strategy.

See Tool Flow for decision trees, bundle internals, and per-tool quick reference.

Project Structure

jenkins-mcp/
├── server.py          # FastMCP server — 20 individual tools + 7 bundles
├── utils/
│   ├── __init__.py
│   ├── jenkins_api.py # Jenkins REST wrappers with retry/backoff
│   ├── junit_parser.py# JUnit XML parser (assertion vs exception classification, blast radius)
│   ├── log_parser.py  # Priority-budgeted error extraction
│   └── scm.py         # changeSet/changeSets normalization across SCMs
├── docs/
│   ├── architecture.md # System design and layer diagrams
│   └── tool-flow.md    # Decision trees and bundle internals
├── tests/             # pytest suite (162 tests)
├── .env               # Your credentials (gitignored)
├── .env.example       # Template
├── .gitignore
└── pyproject.toml

Security

• Credentials are read from environment variables only — never hardcoded.
• The server is read-only: no tools delete jobs, wipe workspaces, or trigger builds.
• The .env file is gitignored by default.
• Console logs are capped at 10 MB to prevent memory exhaustion on large builds.