Metadata-Version: 2.4
Name: camsnetec-jenkins-mcp
Version: 3.1.3
Summary: MCP server for managing Jenkins operations
Author: Kristof Jozsa
Project-URL: Repository, https://github.com/kjozsa/jenkins-mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp
Requires-Dist: python-jenkins
Requires-Dist: loguru
Requires-Dist: requests
Requires-Dist: uvicorn
Requires-Dist: sse-starlette
Requires-Dist: python-dotenv
Dynamic: license-file

# Jenkins MCP
[![smithery badge](https://smithery.ai/badge/@kjozsa/jenkins-mcp)](https://smithery.ai/server/@kjozsa/jenkins-mcp)
MCP server for managing Jenkins operations.

<a href="https://glama.ai/mcp/servers/7j3zk84u5p">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/7j3zk84u5p/badge" alt="Jenkins MCP server" />
</a>

## Installation
### Installing via Smithery

To install Jenkins MCP for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kjozsa/jenkins-mcp):

```bash
npx -y @smithery/cli install @kjozsa/jenkins-mcp --client claude
```

### Installing Manually
```bash
uvx camsnetec-jenkins-mcp
```

### Publishing to PyPI (for maintainers)

```bash
# Install build tools
pip install build twine

# Build the package
cd /path/to/jenkins-mcp
python -m build

# Upload to PyPI (requires PyPI account or API token)
twine upload dist/*

# Or using API token
twine upload -u __token__ -p pypi-YOUR_API_TOKEN dist/*
```

After publishing, users can use the following MCP configuration directly:

## Configuration
Add the MCP server using the following JSON configuration snippet:

```json
{
  "mcpServers": {
    "jenkins-mcp": {
      "command": "uvx",
      "args": ["camsnetec-jenkins-mcp"],
      "env": {
        "JENKINS_URL": "https://your-jenkins-server/",
        "JENKINS_USERNAME": "your-username",
        "JENKINS_PASSWORD": "your-password",
        "JENKINS_USE_API_TOKEN": "false"
      }
    }
  }
}
```

## Transport Modes

The server supports three transport modes, controlled by the `MCP_TRANSPORT` environment variable:

| Mode | Value | Description |
|------|-------|-------------|
| Standard I/O | `stdio` (default) | For local CLI usage (Claude Desktop, Cursor, etc.) |
| SSE | `sse` | Server-Sent Events over HTTP, for cloud deployments |
| Streamable HTTP | `streamable-http` | Recommended for Alibaba Cloud Bailian and similar platforms |

Additional environment variables for HTTP modes (`sse` / `streamable-http`):

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_HOST` | `0.0.0.0` | Bind address |
| `MCP_PORT` | `8000` | Listen port |

## Deploying to Alibaba Cloud Bailian (阿里云百炼)

### 1. Build Docker Image

```bash
docker build -t jenkins-mcp .
```

### 2. Push to Alibaba Cloud Container Registry (ACR)

```bash
# Login to ACR
docker login --username=<your-acr-username> registry.<region>.aliyuncs.com

# Tag the image
docker tag jenkins-mcp registry.<region>.aliyuncs.com/<namespace>/jenkins-mcp:latest

# Push
docker push registry.<region>.aliyuncs.com/<namespace>/jenkins-mcp:latest
```

### 3. Deploy to Function Compute (FC)

Create a function in Alibaba Cloud Function Compute with the following settings:

- **Runtime**: Custom Container
- **Image**: `registry.<region>.aliyuncs.com/<namespace>/jenkins-mcp:latest`
- **Port**: `8000`
- **Environment Variables**:
  ```
  JENKINS_URL=https://your-jenkins-server/
  JENKINS_USERNAME=your-username
  JENKINS_PASSWORD=your-password
  JENKINS_USE_API_TOKEN=false
  MCP_TRANSPORT=streamable-http
  MCP_PORT=8000
  ```

> **Important**: For Bailian platform, **recommended** `MCP_TRANSPORT=streamable-http` with endpoint path `/mcp`. Alternatively use `MCP_TRANSPORT=sse` with endpoint path `/sse`.

### 4. Configure in Bailian MCP Management

In the Bailian console MCP management page:

- **Transport Type**: Select `SSE` or `Streamable HTTP` to match your `MCP_TRANSPORT` setting
- **URL**: Your FC function's public endpoint
  - For SSE: `https://<fc-endpoint>/sse`
  - For Streamable HTTP: `https://<fc-endpoint>/mcp`

### Troubleshooting

If you encounter error `11200053` ("No active SSE connection for session"):
- **Switch to `streamable-http` mode** — this is the recommended transport for cloud deployments as it uses `stateless_http=True` and avoids session affinity issues
- Ensure `MCP_TRANSPORT` is set to `streamable-http` (recommended) or `sse` (not `stdio`)
- Verify the FC function port matches `MCP_PORT` (default `8000`)
- Check that the Bailian transport type matches the server's transport mode
- For SSE mode: enable FC "extreme speed mode" (极速模式), set instance limit to 1, and pre-provision 1 snapshot to ensure session affinity
- For Streamable HTTP mode: no special FC configuration needed — stateless mode works with any number of instances

## CSRF Crumb Handling

Jenkins implements CSRF protection using "crumbs" - tokens that must be included with POST requests. This MCP server handles CSRF crumbs in two ways:

1. **Default Mode**: Automatically fetches and includes CSRF crumbs with build requests
   - Uses session cookies to maintain the web session
   - Handles all the CSRF protection behind the scenes

2. **API Token Mode**: Uses Jenkins API tokens which are exempt from CSRF protection
   - Set `JENKINS_USE_API_TOKEN=true`
   - Set `JENKINS_PASSWORD` to your API token instead of password
   - Works with Jenkins 2.96+ which doesn't require crumbs for API token auth

You can generate an API token in Jenkins at: User → Configure → API Token → Add new Token

## Features
- List Jenkins jobs
- Trigger builds with optional parameters
- Check build status
- CSRF crumb handling for secure API access
- Multiple transport modes (stdio, SSE, Streamable HTTP) for flexible deployment

## Development
```bash
# Install dependencies
uv pip install -r requirements.txt

# Run in dev mode with Inspector
mcp dev jenkins_mcp/server.py

# Run with SSE transport locally
MCP_TRANSPORT=sse jenkins-mcp
```
