README.md•5.3 kB
# mcp_jenkins
A Jenkins MCP server. Model Context Protocol (MCP) lets AI tools (like chatbots) talk to and control your Jenkins setup, i. e. retrieve information and modify settings.
**Note:** This is a minimal experimental version of the MCP Jenkins server and is currently in early development.
## Description
This project provides a Model Context Protocol (MCP) server for interacting with Jenkins. It allows users to trigger Jenkins jobs, get build statuses, and perform other Jenkins-related operations through the MCP interface.
## Components
* [`server.py`](src/mcp_jenkins/server.py): The core MCP Jenkins server application.
* [`functions_schema.md`](src/mcp_jenkins/functions_schema.md): Defines the schema for the functions exposed by the MCP Jenkins server.
* [`client.py`](src/mcp_jenkins/client.py): An example client demonstrating how to interact with the MCP Jenkins server (provided for reference only).
* [`functional tests`](src/mcp_jenkins/tests/functional/test_server.py): Contains functional tests for the MCP Jenkins server.
## Installation
To install the package, run:
```bash
pip install .
```
## Usage
### Common Workflows
#### Running the Server
To run the MCP server:
```bash
./docker/run.server
```
#### Running the Example Client
To run the example client:
```bash
./docker/run.client
```
For example, to list builds for a job named "backups" using a specific model, you can run:
```bash
./docker/run.client --model gemini-2.0-flash-001 "list builds backups"
```
Note: If the package is installed via `pip install .`, the `mcp_jenkins_client` console script is also available.
This might produce output similar to:
```
Query: list builds backups
Result:
Recent builds for backups:
- Build #1086: FAILURE (http://myjenkins:8080/job/backups/1086/)
```
#### Building and Testing with Docker
A common workflow for development and testing is to first build the Docker image and then execute the tests:
1. **Build the Docker image:**
This step prepares the environment needed for testing.
```bash
./docker/build
```
2. **Run tests:**
After the build is complete, execute the tests.
```bash
./docker/run.tests
```
This sequence ensures that tests are performed against the latest build in a consistent Dockerized environment.
#### Deploying a Test Environment
To deploy a local Jenkins testing instance (without authentication, for functional tests only):
```bash
./docker/deploy.test.environment
```
### Connecting to an Existing Jenkins Instance
To use the MCP Jenkins server with an existing Jenkins instance, you need to configure the following environment variables:
* `JENKINS_URL`: The full URL of your Jenkins instance (e.g., `http://your-jenkins-host:8080`). This is **required**.
* `JENKINS_USER`: (Optional) Your Jenkins username if authentication is required.
* `JENKINS_API_TOKEN`: (Optional) Your Jenkins API token. This must be provided along with `JENKINS_USER` if authentication is used. You can generate an API token in your Jenkins user's configuration page (`<Jenkins URL>/me/configure`).
* `MCP_API_KEY`: A secret API key to secure this MCP server. Requests to the MCP server will need to include this key in the `X-API-Key` header. This is **required** unless `DEBUG_MODE` is set to `true`.
* `DEBUG_MODE`: Set to `true` to run the MCP server in debug mode, which bypasses the `MCP_API_KEY` requirement and provides more verbose logging. **Do not use in production.**
**Example Configuration (Bash):**
```bash
export JENKINS_URL="http://your-jenkins-host:8080"
export JENKINS_USER="your_jenkins_username"
export JENKINS_API_TOKEN="your_jenkins_api_token"
export MCP_API_KEY="your_mcp_secret_key"
# export DEBUG_MODE="true" # Uncomment for development/testing without MCP_API_KEY
```
Once these environment variables are set, you can run the MCP server using the Docker script:
```bash
./docker/run.server
```
The MCP server will then attempt to connect to your specified Jenkins instance.
## OpenWebUI Integration
The file `open-webui/open_webui_interface.py` provides an example of how to integrate this MCP Jenkins server with an OpenWebUI instance.
To use it:
1. In your OpenWebUI interface, navigate to the section for adding or configuring tools.
2. Create a new tool.
3. Copy the entire content of the `open-webui/open_webui_interface.py` file and paste it into the tool configuration in OpenWebUI.
4. **Important**: You will need to adjust the connection parameters within the pasted code, specifically:
- `MCP_JENKINS_SERVER_URL`: Set this environment variable in your OpenWebUI environment to the URL of your running MCP Jenkins server (e.g., `http://localhost:5000`). The script defaults to `http://localhost:5000` if the variable is not set.
- `MCP_API_KEY`: If your MCP Jenkins server is configured to require an API key, ensure this environment variable is set in your OpenWebUI environment. The script will print a warning if it's not found but will still attempt to make requests.
Once configured, the tools defined in `open_webui_interface.py` (e.g., `list_jobs`, `trigger_build`, `get_build_status`) should become available for use within your OpenWebUI chat interface.
## License
This project is licensed under the MIT License.