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,避免因参数类型升级导致触发失败。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues