Skip to main content
Glama
Jenkins-MCP
by liozzazhang
README.md
# Jenkins MCP Server

MCP server for Jenkins job operations: info, parameters, build, logs.

## Tools

| Tool | Description |
|------|-------------|
| `get_job_info` | Job info, parameter definitions, last build number |
| `get_build_info` | Build info: result, duration, parameters, commit |
| `get_build_console` | Console output (log text) |
| `trigger_build` | Trigger parameterized build |
| `wait_build_complete` | Poll until build finishes |

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
# 指定公共 PyPI(私有镜像可能没有 mcp)
pip install -e . -i https://pypi.org/simple
# 或: pip install mcp requests python-dotenv && pip install -e . --no-deps
cp .env.example .env
# Edit .env: JENKINS_URL, JENKINS_USER, JENKINS_TOKEN
# 可选:MUC_ANSIBLE_USER, MUC_ANSIBLE_PASSWORD(SSH 凭证,触发 Operations/muc 时自动注入)
```

## Cursor MCP (stdio)

Add to `.cursor/mcp.json` (prefer `run_mcp.sh` so `.env` is sourced; set **`MCP_JENKINS_DIR`** so credential merge finds `mcp-jenkins/.env` when the package runs from site-packages):

```json
{
  "mcpServers": {
    "jenkins": {
      "command": "${workspaceFolder}/../mcp-jenkins/run_mcp.sh",
      "args": [],
      "cwd": "${workspaceFolder}/../mcp-jenkins",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_JENKINS_DIR": "${workspaceFolder}/../mcp-jenkins"
      }
    }
  }
}
```

## Docker + HTTP (streamable-http)

The server defaults to the `streamable-http` transport and exposes the MCP endpoint at `/mcp`. In Docker it binds `0.0.0.0:8000` (override via `MCP_HOST` / `MCP_PORT`).

> Secrets stay in `.env` and are injected at **runtime** (`--env-file` / compose `env_file`). The image never bakes `.env` in (see `.dockerignore`).

### Build & run with docker compose (recommended)

```bash
cd mcp-jenkins
docker compose up -d --build
docker compose logs -f          # expect: "Uvicorn running on http://0.0.0.0:8000"
```

This maps host **`127.0.0.1:8010`** → container `8000`.

### Or with plain docker

```bash
docker build -t mcp-jenkins:latest .
docker run -d --name mcp-jenkins \
  --env-file .env \
  -e MCP_TRANSPORT=streamable-http -e MCP_HOST=0.0.0.0 -e MCP_PORT=8000 \
  -p 127.0.0.1:8010:8000 \
  --security-opt no-new-privileges:true \
  mcp-jenkins:latest
```

### Verify

```bash
curl -i -X POST http://127.0.0.1:8010/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# -> 200 OK, serverInfo.name = "Jenkins-MCP"
```

### Cursor MCP config (HTTP)

Point `.cursor/mcp.json` at the container's HTTP endpoint:

```json
{
  "mcpServers": {
    "jenkins": {
      "url": "http://localhost:8010/mcp"
    }
  }
}
```

If your Cursor version requires an explicit type, use `"type": "streamable-http"` (or `"http"`) alongside `url`. No `.env` is needed in Cursor here — the credentials live in the container.

## Job Path(仅限 Operations folder)

Resources 和 tools 均限制在 **Operations** folder 下:

- `job_path`: `Operations/muc` 或 `Operations/<job_name>`
- 示例:`Operations/muc`、`Operations/job/muc`

## MUC 凭证(Operations/muc)

在 **`mcp-jenkins/.env`** 中配置 `MUC_ANSIBLE_USER`、`MUC_ANSIBLE_PASSWORD`(SSH 账号)。`trigger_build` 会合并为 `ANSIBLE_USER` / `ANSIBLE_SSH_PASSWORD`;**`mcp-jenkins/.env` 优先于**进程环境里残留的 `MUC_*`。查找顺序含 **`MCP_JENKINS_DIR`**(见上)、包内路径、`cwd/.env`。

### 凭证注入异常时的回退策略

若触发后很快失败,且 `get_build_info` 参数里显示 `ANSIBLE_USER` 仍是 job 的默认值或明显出现 SSH 凭证错误,通常表示本次 MCP 未完成 `MUC_* -> ANSIBLE_*` 合并(例如连接到旧版 MCP 实现)。

此时请重试并在 `trigger_build.parameters` 中显式传:

- `ANSIBLE_USER=<MUC_ANSIBLE_USER>`
- `ANSIBLE_SSH_PASSWORD=<MUC_ANSIBLE_PASSWORD>`

同时保留:

- `USE_SSH_KEY=false`
- `USE_SSH_PROXY=false`

## Operations/muc 参数说明

- `PLAYBOOK` 现在是 **Choice** 参数(非自由字符串),请传 Jenkins 可选值之一。
- 典型可选值:`playbooks/health_check.yml`、`playbooks/run.yml`。
- 建议在触发前先调用 `get_job_info` 获取当前 job 的实时 choices,避免因参数类型升级导致触发失败。