Jenkins MCP Server 是一个用于与 Jenkins 服务器交互的 MCP（模型上下文协议）服务器，允许用户通过 MCP 触发任务、查看构建状态并管理 Jenkins 实例。其定位是面向 Jenkins CI/CD 集成的企业级服务器。
主要能力
- 任务管理：触发、列出、搜索和监控 Jenkins 任务，支持文件夹结构。
- 构建状态：实时构建状态跟踪与控制台日志流式获取。
- 流水线支持：逐阶段监控流水线执行，并提供各阶段详细日志。
- 产物管理：跨构建列出、下载和搜索构建产物。
- 批量操作：通过优先级队列并行执行多个任务。
- 高级筛选：按状态、结果、日期等条件筛选任务，支持正则表达式。
性能与可靠性
- 多级缓存系统：五级智能缓存（静态、半静态、动态、短期、永久）。
- 重试逻辑：内置指数退避以提高可靠性。
- CSRF 防护：自动处理 crumb 令牌。
- 输入校验：基于 Pydantic 的健壮校验。
企业特性
- 嵌套任务支持：完整支持 Jenkins 文件夹结构。
- 兼容 2FA：可与 Jenkins 双因素认证配合使用。
- 队列管理：实时构建队列监控。
- 传输灵活性：支持 STDIO 与可流式 HTTP 两种传输方式。
环境要求
- Node.js：14.0.0 或更高版本。
- Python：3.12 或更高版本。
- Jenkins：2.401+（推荐）。
- Jenkins API Token：认证所必需。
安装与配置 安装方式为克隆并安装。自动安装的 Python 包包括：mcp[cli]>=1.11.0（Model Context Protocol）、requests>=2.32.4（HTTP 库）、cachetools>=5.5.0（缓存工具）、python-dotenv（环境变量管理）、pydantic（数据校验）、fastapi（HTTP 传输支持）。需在工作目录创建 .env 文件。
获取 Jenkins API Token 的步骤：登录 Jenkins 服务器；点击用户名 → Configure；在 API Token 区域点击 Add new Token；命名后点击 Generate；复制生成的令牌（之后无法再次查看）。
提供 Claude Desktop 集成方式，需添加到 claude_desktop_config.json。
传输模式
- STDIO 模式（默认）：标准输入输出通信，最适合 Claude Desktop 集成，无需网络端口。
- 可流式 HTTP 模式：基于 HTTP 的通信，适用于 MCP Gateway 或远程连接，需要配置端口。
可用工具（共 21 个 MCP 工具） 任务相关：触发任务（支持参数、任务名或路径，如 "my-job" 或 "folder/my-job"）；获取任务详情（含任务配置、参数、最近构建信息与健康状态，直接查找失败时可进行模式搜索）；列出任务（支持递归、最大深度、是否包含文件夹、按颜色状态、按构建结果如 SUCCESS/FAILURE/UNSTABLE、距上次构建天数、仅启用任务等筛选，返回带统计的分层任务列表）；按模式搜索任务（支持通配符、任务类型筛选 job/folder/pipeline、正则匹配、最大搜索深度）；搜索并触发所有匹配任务；获取文件夹信息（如 "team/project"）。 构建状态与监控：获取指定构建状态（构建号，返回状态、结果、时长、时间戳与执行器信息）；获取构建控制台输出（支持起始字节偏移，返回日志内容与元数据）；获取构建控制台日志的摘要版本。 流水线支持：获取流水线详细执行状态与阶段信息（返回各阶段状态、时长与日志）。 产物管理：列出某次构建的所有产物（含路径、大小与下载 URL）；下载指定构建产物（相对路径，最大下载大小默认 50 MB，二进制以 base64 编码返回）；跨多次构建搜索产物（产物名搜索模式、最多搜索构建数、正则匹配）。 批量操作：并行触发多个任务并带优先级队列（操作列表含任务名、可选参数、优先级，值越大越先执行；设置最大并发数默认 5；可选操作名称；返回用于监控的操作 ID）；监控批量操作状态（按操作 ID 返回各任务状态）；取消批量操作（可选同时取消正在运行的构建）。 队列与服务器管理：获取 Jenkins 构建队列信息（任务名、等待时间与原因）；获取 Jenkins 服务器基本信息（版本、根 URL 与系统信息）。 缓存管理：获取缓存系统统计（命中/未命中率、大小与内存使用）；清除缓存数据（可指定缓存类型如 static、dynamic，或指定任务名）；预填充常用数据以预热缓存。
缓存系统 实现五级缓存系统：静态、半静态、动态、短期、永久。缓存失效时机：任务被触发时、构建状态变化时、手动清除缓存时。缓存行为可通过环境变量自定义。支持预热操作（如 list_jobs、server_info）。
错误处理 提供详细错误信息与建议：404 未找到时给出相似任务名搜索建议；401 未授权时提示检查凭据；403 禁止访问时说明权限问题；连接错误时自动指数退避重试。
嵌套任务支持 完整支持 Jenkins 文件夹结构，所有工具均接受嵌套路径并自动处理。
性能优化 内置优化包括：多级智能缓存、带节流的并发批量操作、请求去重、大数据集惰性加载、可配置内容大小限制。使用建议：对多个任务使用批量操作；对重复操作启用缓存；搜索时设置合适的 max_depth；使用 status_filter 减少数据传输；在高流量时段前预热缓存。
安全 使用 Jenkins API Token 认证；支持 Jenkins 2FA 环境；自动处理 CSRF crumb 令牌。安全特性：不存储密码（仅 API 令牌）；支持 Jenkins HTTPS 端点的 TLS/SSL；对所有参数进行输入校验；可配置产物下载大小限制。
故障排查 涵盖 Python 版本错误、缺失依赖、连接被拒（验证 JENKINS_URL、Jenkins 是否运行、网络连通性）、认证失败（重新生成 API 令牌、核对 JENKINS_USER、检查权限）、任务未找到（核对拼写与大小写、用 search_jobs 查找、检查访问权限）。服务器将日志输出到 stderr 并带请求 ID 便于排查。
许可 Apache License 2.0，详见 LICENSE 文件。版本 1.0.7，最后更新 2025-11-13。
