jenkins-mcp-server

esramirez/jenkins-mcp-server

3.1

If you are the rightful owner of jenkins-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for Jenkins CI/CD integration that enables seamless interaction with Jenkins through natural language queries in MCP-compatible clients.

Tools
5
Resources
0
Prompts
0

Jenkins MCP Server

A Model Context Protocol (MCP) server for Jenkins CI/CD integration that enables seamless interaction with Jenkins through natural language queries in MCP-compatible clients.

License: MIT Python 3.7+

🚀 Features

Jenkins Integration

  • Job Status Monitoring - Get real-time status of Jenkins jobs including build numbers, results, and durations
  • Build Log Retrieval - Fetch console logs for specific builds to analyze failures
  • Job Management - List all available jobs and trigger new builds
  • Queue Monitoring - Monitor Jenkins build queue for pending jobs
  • Multibranch Pipeline Support - Full support for multibranch pipeline projects
  • Connection Debugging - Built-in tools to test and debug Jenkins connectivity

Supported MCP Clients

  • VS Code with MCP extensions
  • Cursor IDE
  • Claude Desktop
  • Any MCP-compatible client

📦 Installation

Prerequisites

  • Python 3.7 or higher
  • Access to a Jenkins server with API enabled
  • Jenkins API token for authentication

Quick Start

  1. Clone the repository:

    git clone https://github.com/your-username/jenkins-mcp-server.git
cd jenkins-mcp-server

  2. Create a virtual environment:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies:

    pip install -r requirements.txt

  4. Set up environment variables:

    # Create a .env file or set environment variables
export JENKINS_URL="https://your-jenkins-server.com/"
export JENKINS_USER="your-username"
export JENKINS_API_TOKEN="your-api-token"

  5. Run the server:

    python src\index.py --mode http --debug

    The server will start on http://localhost:5001 by default.

⚙️ Configuration

Environment Variables

VariableRequiredDescriptionExample
JENKINS_URLYesJenkins server URLhttps://jenkins.example.com/
JENKINS_USERYesJenkins usernameyour-username
JENKINS_API_TOKENYesJenkins API tokenyour-api-token
PORTNoServer port (default: 5001)5001

Jenkins API Token Setup

  1. Log in to your Jenkins server
  2. Go to your user profile → Configure
  3. Scroll down to "API Token" section
  4. Click "Add new Token"
  5. Copy the generated token and use it as JENKINS_API_TOKEN

🛠️ Available Tools

Job Management

  • get_job_status - Get status of a specific Jenkins job
  • get_build_logs - Retrieve console logs for a build
  • list_jobs - List all available Jenkins jobs
  • trigger_job - Start a new build for a job

Monitoring

  • get_queue_info - Get information about queued builds
  • debug_connections - Test Jenkins connectivity and configuration

📝 Usage Examples

Using with VS Code MCP Extension

  1. Install the MCP extension in VS Code (Use the provided example mcp.json)
  2. Configure the Jenkins MCP server in your MCP settings
  3. Use natural language queries like:
    • "What's the status of the develop branch build?"
    • "Show me the logs for the last failed build"
    • "List all jobs in the project"
    • "Trigger a build for the main branch"

Direct API Usage

import requests

# Get job status
response = requests.post('http://localhost:5001/jenkins/get_job_status', 
                        json={'job_name': 'my-project/develop'})
print(response.json())

# Get build logs  
response = requests.post('http://localhost:5001/jenkins/get_build_logs',
                        json={'job_name': 'my-project/develop', 'build_number': 123})
print(response.json())

🧪 Testing

Run the test suite:

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_jenkins_handlers.py

# Run with coverage
python -m pytest tests/ --cov=src

📁 Project Structure

jenkins-mcp-server/
├── src/
│   ├── index.py              # Main MCP server entry point
│   └── tools/
│       ├── jenkins_tools.py  # Tool definitions
│       └── handlers/
│           ├── jenkins_handlers.py  # Jenkins API handlers
│           └── debug_handlers.py    # Debug utilities
├── tests/                    # Test files
├── app.py                   # Flask application entry point
├── requirements.txt         # Python dependencies
├── README.md               # This file
├── CONTRIBUTING.md         # Contribution guidelines
└── LICENSE                 # MIT License

🚗 Roadmap

🎯 Planned Features

Phase 1: Core Improvements
  • Response Caching - Implement intelligent caching to reduce Jenkins server load
    • Cache job status for configurable time intervals
    • Cache build logs for completed builds
    • Implement cache invalidation strategies
  • Enhanced Error Handling - Improve error messages and recovery mechanisms
  • Configuration Validation - Add startup validation for Jenkins connectivity
Phase 2: Advanced Features
  • Pipeline Visualization - Generate visual representations of Jenkins pipelines
  • Build Comparison - Compare builds across different branches or time periods
  • Notification Integration - Support for Slack, Teams, and email notifications
  • Metrics Dashboard - Build success rates, duration trends, and performance metrics
Phase 3: Deployment & Operations
  • Containerization - Docker support for easy deployment 
    # Planned Docker setup
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5001
CMD ["python", "app.py"]
  • Kubernetes Deployment - Helm charts and K8s manifests
  • Health Monitoring - Prometheus metrics and health check endpoints
  • Authentication - Support for OAuth and API key authentication
Phase 4: Enterprise Features
  • Multi-Jenkins Support - Connect to multiple Jenkins instances
  • Role-Based Access - Implement permission-based tool access
  • Audit Logging - Track all API calls and user actions
  • High Availability - Support for load balancing and failover

🎉 Community Contributions

We welcome contributions in these areas:

  • Integrations - Support for other CI/CD platforms (GitHub Actions, GitLab CI)
  • Plugins - Custom Jenkins plugin integrations
  • UI Components - Web dashboard for non-MCP usage
  • Documentation - Tutorials, examples, and best practices

🤝 Contributing

We welcome contributions! Please see for details on:

  • Development setup
  • Code style guidelines
  • Testing requirements
  • Pull request process

Quick Contributing Steps

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run the test suite: python -m pytest tests/
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

🙏 Acknowledgments

⭐ Star this repository if you find it useful! DEBUG=true


### Running the Server

1. **Using the batch file** (Windows):
   ```batch
   run.bat

  1. Using Python directly:

    python src/index.py

  2. Using environment variables:

    export JENKINS_URL="http://your-jenkins-server/"
export JENKINS_USER="your-username"
export JENKINS_API_TOKEN="your-token"
python src/index.py

MCP Client Configuration

VS Code

Add to your .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jenkins-url",
      "description": "Jenkins Server URL",
      "default": "http://mycompany.com/"
    },
    {
      "type": "promptString",
      "id": "jenkins-user", 
      "description": "Jenkins Username"
    },
    {
      "type": "promptString",
      "id": "jenkins-token",
      "description": "Jenkins API Token",
      "password": true
    }
  ],
  "servers": {
    "jenkins-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "${input:jenkins-url}",
        "JENKINS_USER": "${input:jenkins-user}",
        "JENKINS_API_TOKEN": "${input:jenkins-token}"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server/",
        "JENKINS_USER": "your-username", 
        "JENKINS_API_TOKEN": "your-token"
      }
    }
  }
}

Cursor IDE

Add to your cursor MCP config:

{
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server/",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-token"
      }
    }
  }
}

Usage Examples

Using MCP Tools

  1. Check Jenkins job status:

    "Get the status of the MyAwesome job"

  2. List all Jenkins jobs:

    "List all available Jenkins jobs"

  3. Get build logs:

    "Get the console logs for the latest MyAwesome build"

  4. Trigger a job:

    "Trigger the MyAwesome job"

Using REST API

# Get job status
curl "http://localhost:5001/context/job-status?job=MyAwesome"



## Troubleshooting

1. **Connection issues**: Use the `debug_connections` tool to check Jenkins and Metabase connectivity
2. **Authentication**: Ensure Jenkins API token has necessary permissions
3. **Environment variables**: Verify all required environment variables are set
4. **Port conflicts**: Change the PORT environment variable if 5001 is in use

## License

MIT License