jenkins-mcp

一个面向 Jenkins 发布场景的 MCP Server。

对外提供三个工具：

• trigger_deploy
• get_build_status
• setup_github_actions

设计目标：让 Agent 用最少步骤完成"触发发布 + 跟踪状态"。

这个工具做什么（给人看）

• 触发 Jenkins 发布流水线
• 查询队列/构建状态
• 自动定位项目（优先使用已有映射，其次用仓库 origin 与 Jenkins SCM 精确匹配）
• 初始化 GitHub PR 评论触发的部署工作流（/deploy info / /deploy test）

成功触发后，返回可直接打开的 build_url。

前置条件

使用 GitHub Packages 源，需要在 ~/.npmrc 中配置 registry，参见下方 Registry 配置。

快速开始

方式一：交互式初始化（推荐）

npx @difftim/jenkins-mcp init

按提示输入 Jenkins URL，拖入证书文件（.p12 会自动转换为 PEM），自动生成配置文件。然后挂载到 Agent：

claude mcp add jenkins \
  --env JENKINS_USERNAME=YOUR_USERNAME \
  --env JENKINS_PASSWORD=YOUR_PASSWORD \
  -- npx @difftim/jenkins-mcp

方式二：零配置模式（纯环境变量）

不需要任何配置文件，直接通过环境变量启动：

claude mcp add jenkins \
  --env JENKINS_BASE_URL=https://jenkins.example.com \
  --env JENKINS_USERNAME=YOUR_USERNAME \
  --env JENKINS_PASSWORD=YOUR_PASSWORD \
  --env JENKINS_TLS_P12_PATH=/path/to/client.p12 \
  --env JENKINS_TLS_P12_PASSPHRASE=cert_password \
  -- npx @difftim/jenkins-mcp

.p12 证书会在启动时自动转换为 PEM 格式。适合快速分享给同事 — 一行命令搞定。

方式三：手动配置

如需自定义参数，手动创建配置文件：

mkdir -p ~/.config/jenkins-mcp
npx @difftim/jenkins-mcp --help  # 查看配置路径和环境变量列表

配置文件：

• ~/.config/jenkins-mcp/config.toml — Jenkins 连接与 TLS 配置

模板见 config/config.example.toml。

挂载到 Agent

Claude Code

claude mcp add jenkins \
  --env JENKINS_USERNAME=YOUR_USERNAME \
  --env JENKINS_PASSWORD=YOUR_PASSWORD \
  -- npx @difftim/jenkins-mcp

Codex CLI

codex mcp add jenkins \
  --env JENKINS_USERNAME="YOUR_USERNAME" \
  --env JENKINS_PASSWORD="YOUR_PASSWORD" \
  -- npx @difftim/jenkins-mcp

Auto-deploy Hook（Claude Code）

如果你希望 git push 后自动触发部署，可以在项目的 .claude/settings.json 中添加 hook：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(*push*)",
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/settings.json .claude/settings.local.json ~/.claude/settings.json 2>/dev/null | grep -q 'jenkins-mcp' || exit 1"
          },
          {
            "type": "agent",
            "prompt": "A git push was just completed. Call the trigger_deploy tool from the jenkins MCP server to deploy.",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Bash(*push*) 会匹配所有包含 "push" 的 Bash 命令（git push、ggpush 等），command hook 再检查当前环境是否注册了 jenkins-mcp，两层过滤确保不会误触发。

GitHub Actions ChatOps

在已经挂载 jenkins-mcp、且当前目录有 GitHub origin remote 的项目里，可以让 Agent 调用：

setup_github_actions

它会写入 .github/workflows/pr-jenkins-deploy.yml，让 PR 评论支持：

/deploy info
/deploy test

默认会尝试通过 gh CLI 写入可从当前 MCP 配置推导出的 GitHub Variables/Secrets：

• Variables: JENKINS_URL, JENKINS_JOB_NAME, JENKINS_BRANCH_PARAM_NAME, JENKINS_VERSION_PARAM_NAME, JENKINS_USER
• Secrets: JENKINS_PASSWORD, JENKINS_CLIENT_CERT_BASE64 + JENKINS_CLIENT_KEY_BASE64
• 如果当前配置使用 .p12，则写入 JENKINS_CLIENT_P12_BASE64 和可用时的 JENKINS_CLIENT_P12_PASSPHRASE

如果某些值不在当前环境里（例如 Jenkins 密码来自本机 Keychain 而不是环境变量），工具会在 manual_setup 返回需要用户手动补的 GitHub secret/variable。工作流文件需要提交到仓库默认分支后，PR 评论触发才会生效。

Agent 运行约定（建议）

• 优先调用 trigger_deploy 发起发布。
• 若返回 status: "no_match"：
  • 让用户提供 project_id，或
  • 先补充 repo-job 映射后重试。
• 发布后使用 get_build_status 轮询到 finished。

快速验证

1. 启动后看到日志：[jenkins-mcp] started ...
2. trigger_deploy 返回 status: "triggered" 且包含 build_url
3. get_build_status 可查询到对应构建状态

Registry 配置

本包发布在 GitHub Packages，使用前需要在 ~/.npmrc 中添加：

@difftim:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Token 需要 read:packages scope，在 GitHub Settings > Tokens 生成。

开发命令

npm run dev      # 直接运行 TypeScript 源码
npm run test     # 运行测试
npm run build    # 构建到 dist/

License

MIT