# Jenkins MCP

一个基于 Jenkins REST API 的 MCP Server，目标是兼容 Jenkins 2.332.2、2.356 以及后续版本。

它不安装 Jenkins 插件，因此不会受到官方 `mcp-server` 插件最低 Jenkins 核心版本的限制。一个 MCP Server 可以在配置中同时管理多个 Jenkins 实例，并通过 `jenkins_name` 选择目标实例。

## 已实现能力

- 查询 Jenkins 版本和兼容能力
- 查询当前认证用户
- 查询根目录或 Folder 下的 Job
- 查询 Job 和 Build
- 获取构建日志，并限制返回行数
- 查询 Queue、Queue Item 和节点
- 触发构建、停止构建、取消排队构建
- 用户名 + API Token 认证
- 自动获取和重试 Jenkins CSRF Crumb
- 默认只读，写操作需要显式设置 `read_only: false`

## 安装

建议使用 Python 3.10 或更高版本：

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
```

## 多 Jenkins 配置

创建 `jenkins-mcp.json`：

```json
{
  "instances": [
    {
      "name": "jenkins-233",
      "base_url": "https://jenkins-233.example.com",
      "username": "mcp-user",
      "api_token": "replace-me",
      "read_only": true,
      "verify_ssl": true,
      "timeout_seconds": 30,
      "max_log_lines": 2000
    },
    {
      "name": "jenkins-356",
      "base_url": "https://jenkins-356.example.com/jenkins",
      "username": "mcp-user",
      "api_token": "replace-me",
      "read_only": false
    }
  ],
  "server": {
    "transport": "stdio",
    "log_level": "INFO"
  }
}
```

启动：

```bash
jenkins-mcp --config jenkins-mcp.json
```

也可以使用配置目录，每个 JSON 文件配置一个 Jenkins：

```text
jenkins-mcp.d/
├── jenkins-233.json
└── jenkins-356.json
```

文件内容使用单个实例格式：

```json
{
  "name": "jenkins-233",
  "base_url": "https://jenkins-233.example.com",
  "username": "mcp-user",
  "api_token": "replace-me",
  "read_only": true
}
```

启动：

```bash
jenkins-mcp --config-dir jenkins-mcp.d
```

运行中的服务会在每次 MCP 工具调用前检查配置文件变化。新增、修改或删除目录中的
`*.json` 文件后，下一次调用即可生效，不需要重启服务。配置文件格式错误或实例名称
重复时，服务会保留上一份有效配置。

生产环境建议通过环境变量或密钥管理系统注入配置，不要把 API Token 提交到 Git。

## 配置文件放置建议

程序不会自动创建或猜测配置目录，必须通过 `--config`、`--config-dir` 或对应环境变量
明确指定配置位置。建议将程序文件和敏感配置分开：

Windows：

```text
C:\Tools\jenkins-mcp\           # 程序和虚拟环境
C:\ProgramData\jenkins-mcp\     # 运行配置
└── instances\
    ├── jenkins-233.json
    └── jenkins-356.json
```

Linux：

```text
/opt/jenkins-mcp/                # 程序和虚拟环境
/etc/jenkins-mcp/                # 运行配置
└── instances/
    ├── jenkins-233.json
    └── jenkins-356.json
```

以上是部署建议，不是固定默认路径。开发时也可以直接使用仓库下的
`config/jenkins-mcp.d/`，但不要将真实 Token 提交到 Git。

目录模式中，只有配置目录顶层的 `*.json` 文件会被扫描；文件名可以自定义，实际实例名
由 JSON 中的 `name` 字段决定。单文件模式使用包含 `instances` 数组的总配置文件，不能把
这个总配置文件放入目录模式中。

## Windows 启动

在 PowerShell 中从仓库目录执行：

```powershell
Set-Location D:\imax\i-mcp\jenkins-mcp
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install .
```

使用配置目录启动：

```powershell
.\.venv\Scripts\jenkins-mcp.exe `
  --config-dir C:\ProgramData\jenkins-mcp\instances
```

也可以使用仓库源码入口：

```powershell
.\.venv\Scripts\python.exe -m jenkins_mcp `
  --config-dir C:\ProgramData\jenkins-mcp\instances
```

使用总配置文件启动：

```powershell
.\.venv\Scripts\jenkins-mcp.exe `
  --config C:\ProgramData\jenkins-mcp\jenkins-mcp.json
```

不想在命令行写路径时，可以设置环境变量：

```powershell
$env:JENKINS_CONFIG_DIR = "C:\ProgramData\jenkins-mcp\instances"
\.venv\Scripts\jenkins-mcp.exe
```

配置文件建议使用 Windows ACL 限制访问权限，至少不要让普通用户读取包含 Token 的文件。

## Linux 启动

```bash
cd /opt/jenkins-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .
sudo install -d -m 700 /etc/jenkins-mcp/instances
sudo chmod 600 /etc/jenkins-mcp/instances/*.json
```

如果使用下面的 systemd 示例，请先确保 `jenkins-mcp` 系统用户存在，并将配置目录和
文件授权给该用户读取，例如：

```bash
sudo useradd --system --home-dir /opt/jenkins-mcp --shell /usr/sbin/nologin jenkins-mcp
sudo chown -R jenkins-mcp:jenkins-mcp /opt/jenkins-mcp
sudo chown -R root:jenkins-mcp /etc/jenkins-mcp
sudo chmod 750 /etc/jenkins-mcp/instances
sudo chmod 640 /etc/jenkins-mcp/instances/*.json
```

前台启动：

```bash
/opt/jenkins-mcp/.venv/bin/jenkins-mcp \
  --config-dir /etc/jenkins-mcp/instances
```

Linux 服务器上使用 HTTP 传输时，可以通过配置文件的 `server` 节指定监听参数：

```json
{
  "instances": [
    {
      "name": "jenkins-233",
      "base_url": "https://jenkins.example.com",
      "username": "mcp-user",
      "api_token": "replace-me",
      "read_only": true
    }
  ],
  "server": {
    "transport": "streamable-http",
    "host": "127.0.0.1",
    "port": 8000,
    "log_level": "INFO"
  }
}
```

然后执行：

```bash
/opt/jenkins-mcp/.venv/bin/jenkins-mcp \
  --config /etc/jenkins-mcp/jenkins-mcp.json
```

stdio 模式通常由 MCP 客户端自动拉起，不需要 systemd。HTTP 模式作为常驻服务时，可使用
systemd，例如 `/etc/systemd/system/jenkins-mcp.service`：

```ini
[Unit]
Description=Jenkins MCP Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=jenkins-mcp
WorkingDirectory=/opt/jenkins-mcp
ExecStart=/opt/jenkins-mcp/.venv/bin/jenkins-mcp --config-dir /etc/jenkins-mcp/instances
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now jenkins-mcp
sudo systemctl status jenkins-mcp
```

Windows 上如果需要 HTTP 常驻服务，可以使用 Windows 服务包装器（例如 NSSM）托管
`.venv\Scripts\jenkins-mcp.exe`：

```powershell
nssm install JenkinsMcp C:\Tools\jenkins-mcp\.venv\Scripts\jenkins-mcp.exe
nssm set JenkinsMcp AppDirectory C:\Tools\jenkins-mcp
nssm set JenkinsMcp AppParameters "--config-dir C:\ProgramData\jenkins-mcp\instances"
nssm start JenkinsMcp
```

stdio 模式仍建议由 MCP 客户端直接启动。

## MCP 客户端连接

stdio 模式下，Windows 客户端配置示例：

```json
{
  "mcpServers": {
    "jenkins": {
      "command": "C:\\Tools\\jenkins-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "jenkins_mcp",
        "--config-dir",
        "C:\\ProgramData\\jenkins-mcp\\instances"
      ]
    }
  }
}
```

Linux 客户端配置示例：

```json
{
  "mcpServers": {
    "jenkins": {
      "command": "/opt/jenkins-mcp/.venv/bin/python",
      "args": [
        "-m",
        "jenkins_mcp",
        "--config-dir",
        "/etc/jenkins-mcp/instances"
      ]
    }
  }
}
```

启动后，先调用 `list_jenkins_instances` 确认实例名称，再在其他工具中使用对应的
`jenkins_name`。

例如：

```text
list_jobs(jenkins_name="jenkins-233")
get_build_log(jenkins_name="jenkins-356", job_name="team/app", build_number=123)
```

## 打包与分发

这是纯 Python 项目，推荐打包成 wheel，再在目标操作系统创建各自的虚拟环境。不要直接
复制 Windows 的 `.venv` 到 Linux，或反向复制。

在仓库根目录执行：

```bash
python -m pip install --upgrade build
python -m build
```

Windows 使用 `py -3 -m build`，Linux 使用 `python3 -m build`。产物位于 `dist/`：

```text
dist/
├── jenkins_mcp-0.1.0-py3-none-any.whl
└── jenkins_mcp-0.1.0.tar.gz
```

在 Windows 安装 wheel：

```powershell
py -3 -m venv C:\Tools\jenkins-mcp\.venv
C:\Tools\jenkins-mcp\.venv\Scripts\python.exe -m pip install `
  .\dist\jenkins_mcp-0.1.0-py3-none-any.whl
```

在 Linux 安装 wheel：

```bash
python3 -m venv /opt/jenkins-mcp/.venv
/opt/jenkins-mcp/.venv/bin/python -m pip install \
  ./dist/jenkins_mcp-0.1.0-py3-none-any.whl
```

wheel 本身是跨平台的，但依赖需要在目标系统中安装。离线部署时，应分别在 Windows 和
Linux 目标环境准备对应的依赖包目录，然后执行：

```bash
python -m pip install --no-index --find-links wheelhouse \
  jenkins_mcp-0.1.0-py3-none-any.whl
```

## 动态配置生效规则

- 使用 `--config-dir` 或 `JENKINS_CONFIG_DIR` 时，新增、修改、删除顶层 `*.json` 后，下一次
  MCP 调用生效，不需要重启；
- 使用 `--config` 或 `JENKINS_CONFIG_FILE` 时，修改总配置文件中的 `instances` 后，下一次
  MCP 调用同样生效；
- `JENKINS_INSTANCES_JSON`、`JENKINS_URL` 等纯环境变量模式只在进程启动时读取；
- 配置文件格式错误、实例名称重复或目录没有有效 JSON 时，继续使用上一份有效配置；
- 修改或删除实例时，正在执行的请求完成后才释放旧 HTTP 连接；
- 配置目录与总配置文件不能同时指定。

HTTP 模式当前不提供独立的 MCP 用户认证。生产环境建议只监听 `127.0.0.1`，或在反向
代理层配置 TLS、访问控制和认证后再对外提供服务。

## 单 Jenkins 环境变量配置

也可以使用以下变量：

```bash
export JENKINS_URL='https://jenkins.example.com'
export JENKINS_USERNAME='mcp-user'
export JENKINS_API_TOKEN='replace-me'
export JENKINS_READ_ONLY='true'
jenkins-mcp
```

多实例也可以把 JSON 数组放入 `JENKINS_INSTANCES_JSON`。`--config`、`--config-dir`
分别覆盖对应的环境变量；单文件和目录模式不能同时配置。

## 版本兼容策略

服务通过 Jenkins 的 `X-Jenkins` 响应头检测版本。`2.332.2` 是当前最低兼容基线，`2.356` 使用相同的基础 REST API 能力。版本相关差异放在 `versioning.py` 的能力模型中，MCP 工具层不直接写版本判断。

基础 REST API 比 Jenkins 插件 API 更适合跨版本使用，但插件特有功能、Pipeline 高级信息和凭据管理不作为当前跨版本保证的一部分。

## 开发

```bash
pytest
ruff check .
```