Jenkins MCP Server

🚀 Jenkins MCP Server

Jenkins MCP Server 是一款企业级的 MCP（模型上下文协议）服务器，可实现与 Jenkins CI/CD 的无缝集成。它允许像 Claude 这样的 AI 助手通过全面且适用于生产环境的 API 与 Jenkins 进行交互。

🚀 快速开始

npm 安装（推荐）

# 全局安装
npm install -g @ashwinighuge/jenkins-mcp-server

# 或者直接使用 npx
npx @ashwinighuge/jenkins-mcp-server --help

与 Claude Desktop 集成

将以下内容添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "jenkins": {
      "command": "jenkins-mcp",
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

✨ 主要特性

• 🔧 任务管理：支持触发、列出、搜索和监控 Jenkins 任务，全面支持文件夹操作。
• 📊 构建状态：实时跟踪构建状态，并支持控制台日志流式传输。
• 🔄 流水线支持：逐阶段监控流水线执行情况，并提供详细日志。
• 📦 制品管理：可跨多个构建列出、下载和搜索构建制品。
• ⚡ 批量操作：支持并行任务执行，并具备智能优先级排队功能。
• 🚀 性能缓存：采用多级智能缓存系统，支持自动失效机制。
• 🔍 高级过滤：支持通过状态、结果、日期等条件过滤任务，同时支持正则表达式。
• 📋 队列管理：实时监控和管理构建队列。
• 🔒 企业安全：提供 CSRF 保护、2FA 支持和安全认证。
• 🌐 跨平台：支持在 Windows、macOS 和 Linux 系统上运行。
• 🔄 重试逻辑：内置指数退避机制，提高可靠性。
• 📡 传输灵活性：支持 STDIO 和 HTTP 两种传输方式。
• ✅ 输入验证：基于 Pydantic 实现强大的验证和错误处理。

📋 前提条件

• Node.js：版本 14.0.0 或更高。
• Python：版本 3.12 或更高。
• Jenkins：建议版本 2.401+。
• Jenkins API 令牌：用于身份验证。

📦 安装指南

方法 1：npm（推荐）

# 全局安装，以便在系统范围内使用
npm install -g @ashwinighuge/jenkins-mcp-server

# 验证安装
jenkins-mcp --help

方法 2：开发环境设置

# 克隆仓库
git clone https://github.com/AshwiniGhuge3012/jenkins-mcp-server
cd jenkins-mcp-server

# 安装 Node.js 依赖
npm install

# 安装 Python 依赖
pip install -r requirements.txt  # 或者使用 uv pip install

# 本地运行
node bin/jenkins-mcp.js --help

🔐 配置

环境变量

在工作目录中创建一个 .env 文件：

# 必需的 Jenkins 配置
JENKINS_URL="http://your-jenkins-server:8080"
JENKINS_USER="your-username"
JENKINS_API_TOKEN="your-api-token"

# 可选：服务器配置
MCP_PORT=8010
MCP_HOST=0.0.0.0

# 可选：重试配置
JENKINS_MAX_RETRIES=3
JENKINS_RETRY_BASE_DELAY=1.0
JENKINS_RETRY_MAX_DELAY=60.0
JENKINS_RETRY_BACKOFF_MULTIPLIER=2.0

# 可选：性能缓存配置
JENKINS_CACHE_STATIC_TTL=3600        # 1 小时
JENKINS_CACHE_SEMI_STATIC_TTL=300    # 5 分钟
JENKINS_CACHE_DYNAMIC_TTL=30         # 30 秒
JENKINS_CACHE_SHORT_TTL=10           # 10 秒
JENKINS_CACHE_STATIC_SIZE=1000       # 最大缓存项数
JENKINS_CACHE_SEMI_STATIC_SIZE=500
JENKINS_CACHE_DYNAMIC_SIZE=200
JENKINS_CACHE_PERMANENT_SIZE=2000
JENKINS_CACHE_SHORT_SIZE=100

获取 Jenkins API 令牌

1. 登录到你的 Jenkins 实例。
2. 点击你的用户名，然后选择 配置。
3. 滚动到 API 令牌 部分。
4. 点击 添加新令牌。
5. 为令牌命名，然后点击 生成。
6. 复制生成的令牌（请妥善保存！）

💻 使用示例

命令行界面

# STDIO 模式（默认，适用于 Claude Desktop）
jenkins-mcp

# HTTP 模式（适用于 MCP 网关）
jenkins-mcp --transport streamable-http --port 8010

# 自定义主机和端口
jenkins-mcp --transport streamable-http --host localhost --port 9000

# 显示帮助信息
jenkins-mcp --help

传输模式

高级用法示例

# 使用 npx（无需全局安装）
npx @ashwinighuge/jenkins-mcp-server

# 使用环境变量
JENKINS_URL=http://localhost:8080 JENKINS_USER=admin JENKINS_API_TOKEN=abc123 jenkins-mcp

# 自定义配置的 HTTP 模式
jenkins-mcp --transport streamable-http --host 0.0.0.0 --port 8080

可用工具

以下是该 MCP 服务器提供的工具列表：

trigger_job

• 描述：触发一个 Jenkins 任务，可选择传入参数。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • params（对象，可选）：任务参数，以 JSON 对象形式传入。对于多选参数，请传入字符串数组。
• 返回值：包含队列 URL 的确认消息。

get_job_info

• 描述：获取 Jenkins 任务的详细信息，包括其参数。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
• 返回值：包含任务描述、参数和最后一次构建编号的对象。

get_build_status

• 描述：获取特定构建的状态。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • build_number（整数）：构建编号。
• 返回值：包含构建状态、时间戳、持续时间和 URL 的对象。

get_console_log

• 描述：获取特定构建的控制台日志。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • build_number（整数）：构建编号。
  • start（整数，可选）：获取日志的起始字节位置。
• 返回值：控制台日志文本以及是否还有更多数据的信息。

list_jobs

• 描述：列出 Jenkins 服务器上所有可用的任务，并具备高级过滤功能。
• 参数：
  • recursive（布尔值，可选）：如果为 True，则递归遍历文件夹（默认值：True）
  • max_depth（整数，可选）：递归的最大深度（默认值：10）
  • include_folders（布尔值，可选）：是否包含文件夹项（默认值：False）
  • status_filter（字符串，可选）：按任务状态过滤："building"、"queued"、"idle"、"disabled"
  • last_build_result（字符串，可选）：按最后一次构建结果过滤："SUCCESS"、"FAILURE"、"UNSTABLE"、"ABORTED"、"NOT_BUILT"
  • days_since_last_build（整数，可选）：仅显示最近 N 天内构建过的任务
  • enabled_only（布尔值，可选）：如果为 True，则仅显示启用的任务；如果为 False，则仅显示禁用的任务
• 返回值：包含增强元数据（如构建状态和时间戳）的任务列表。

search_jobs

• 描述：使用模式匹配和高级过滤功能搜索 Jenkins 任务。
• 参数：
  • pattern（字符串）：用于匹配任务名称的模式（支持通配符，如 'build*'、'test' 等）
  • job_type（字符串，可选）：按类型过滤 - "job"、"folder" 或 "all"（默认值："job"）
  • max_depth（整数，可选）：搜索的最大深度（默认值：10）
  • use_regex（布尔值，可选）：如果为 True，则将模式视为正则表达式而非通配符（默认值：False）
  • status_filter（字符串，可选）：按任务状态过滤："building"、"queued"、"idle"、"disabled"
  • last_build_result（字符串，可选）：按最后一次构建结果过滤："SUCCESS"、"FAILURE"、"UNSTABLE"、"ABORTED"、"NOT_BUILT"
  • days_since_last_build（整数，可选）：仅显示最近 N 天内构建过的任务
  • enabled_only（布尔值，可选）：如果为 True，则仅显示启用的任务；如果为 False，则仅显示禁用的任务
• 返回值：包含增强元数据和完整路径的匹配任务列表。

get_queue_info

• 描述：获取当前队列中构建的信息。
• 参数：无
• 返回值：队列中的项目列表。

server_info

• 描述：获取 Jenkins 服务器的基本信息。
• 参数：无
• 返回值：Jenkins 版本和 URL。

get_pipeline_status

• 描述：获取 Jenkins 流水线任务构建的详细阶段状态。
• 参数：
  • job_name（字符串）：Jenkins 流水线任务的名称。
  • build_number（整数）：构建编号。
• 返回值：包含逐阶段状态、时间、持续时间和日志的流水线执行详细信息。

list_build_artifacts

• 描述：列出特定 Jenkins 构建的所有制品。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • build_number（整数）：要列出制品的构建编号。
• 返回值：包含所有制品信息（如文件名、大小和下载 URL）。

download_build_artifact

• 描述：下载特定构建制品的内容（为安全起见，仅支持文本制品）。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • build_number（整数）：包含制品的构建编号。
  • artifact_path（字符串）：制品的相对路径（从 list_build_artifacts 获取）。
  • max_size_mb（整数，可选）：下载的最大文件大小（以 MB 为单位，默认值：50MB）。
• 返回值：制品内容（对于文本文件）或下载信息。

search_build_artifacts

• 描述：使用模式匹配在任务的最近构建中搜索制品。
• 参数：
  • job_name（字符串）：要搜索的 Jenkins 任务的名称。
  • pattern（字符串）：用于匹配制品名称的模式（通配符或正则表达式）。
  • max_builds（整数，可选）：搜索的最近构建的最大数量（默认值：10）。
  • use_regex（布尔值，可选）：如果为 True，则将模式视为正则表达式而非通配符（默认值：False）。
• 返回值：跨构建的匹配制品列表及其元数据。

batch_trigger_jobs

• 描述：批量触发多个 Jenkins 任务，支持并行执行和优先级排队。
• 参数：
  • operations（数组）：任务操作列表，每个操作包含：
    • job_name（字符串）：Jenkins 任务的名称
    • params（对象，可选）：任务参数
    • priority（整数，可选）：优先级 1 - 10（1 为最高，默认值：1）
  • max_concurrent（整数，可选）：最大并发任务触发数（默认值：5）
  • fail_fast（布尔值，可选）：遇到第一个失败时停止处理（默认值：false）
  • wait_for_completion（布尔值，可选）：等待所有任务完成（默认值：false）
• 返回值：包含操作 ID、结果和执行统计信息的批量操作响应。

batch_monitor_jobs

• 描述：监控批量操作及其各个任务的状态。
• 参数：
  • operation_id（字符串）：batch_trigger_jobs 返回的操作 ID。
• 返回值：批量操作的当前状态，包括进度和各个任务的状态。

batch_cancel_jobs

• 描述：取消批量操作，并可选择取消正在运行的构建。
• 参数：
  • operation_id（字符串）：要取消的操作 ID。
  • cancel_running_builds（布尔值，可选）：尝试取消正在运行的构建（默认值：false）。
• 返回值：取消状态和结果。

get_cache_statistics

• 描述：获取全面的缓存性能指标和利用率统计信息。
• 参数：无
• 返回值：所有缓存类型的缓存命中率、利用率百分比和详细统计信息。

clear_cache

• 描述：精细控制清除缓存，以进行性能管理。
• 参数：
  • cache_type（字符串，可选）：要清除的缓存类型（'all'、'static'、'semi_static'、'dynamic'、'permanent'、'short'）
  • job_name（字符串，可选）：仅清除特定任务的缓存
• 返回值：缓存清除操作的确认信息。

warm_cache

• 描述：将频繁访问的数据预加载到缓存中，以提高性能。
• 参数：
  • operations（数组，可选）：要预热的操作（'server_info'、'job_list'、'queue_info'）
• 返回值：包含成功/失败状态的缓存预热操作结果。

summarize_build_log

• 描述：（演示）使用预配置的大语言模型提示总结构建日志。
• 参数：
  • job_name（字符串）：Jenkins 任务的名称。
  • build_number（整数）：构建编号。
• 返回值：占位符摘要和将使用的提示。

与 Claude Desktop 配合使用

在 claude_desktop_config.json 中完成配置后，你可以向 Claude 提问：

"列出所有 Jenkins 任务"

"使用版本参数 1.2.3 触发 deploy-prod 任务"

"显示 api-tests 任务第 45 次构建的控制台日志"

"过去 24 小时内所有失败任务的状态如何？"

与 MCP 网关配合使用

# 以 HTTP 模式启动服务器
jenkins-mcp --transport streamable-http --port 8010

# 示例 API 调用（使用 curl）
curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "list_jobs", "arguments": {}}}'

批量操作示例

# 以不同优先级触发多个任务
jenkins-mcp # 然后使用 batch_trigger_jobs 工具，传入以下内容：
{
  "operations": [
    {"job_name": "unit-tests", "priority": 1},
    {"job_name": "integration-tests", "priority": 2},
    {"job_name": "deploy-staging", "priority": 3}
  ],
  "max_concurrent": 3,
  "wait_for_completion": true
}

🔧 技术细节

常见问题

Python 依赖问题

# 如果 Python 包自动安装失败
pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

# 或者使用 uv（推荐）
uv pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

权限问题（Linux/macOS）

# 如果权限被拒绝
sudo npm install -g @ashwinighuge/jenkins-mcp-server

# 或者使用用户级安装
npm install -g @ashwinighuge/jenkins-mcp-server --prefix ~/.local

Jenkins 连接问题

• 验证 JENKINS_URL 是否可访问。
• 确保 API 令牌有效且未过期。
• 检查防火墙/代理设置。
• 对于 HTTPS，验证 SSL 证书。

2FA/CSRF 问题

• 服务器会自动处理 CSRF 令牌。
• 对于 2FA 环境，请使用 API 令牌（而非密码）。
• 支持电子邮件 OTP 等 2FA 方法。

调试模式

# 启用详细日志记录
DEBUG=jenkins-mcp jenkins-mcp

# 检查 Python 依赖
jenkins-mcp --help  # 将验证依赖项

性能特性

• 多级缓存：智能缓存，支持自动失效机制。
• 批量处理：并行任务执行，具备智能优先级排队功能。
• 重试逻辑：指数退避机制，提高网络可靠性。
• 连接池：高效的 HTTP 连接管理。
• 内存优化：可配置缓存大小和 TTL 值。

🤝 贡献代码

1. 分叉仓库。
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送至分支：git push origin feature/amazing-feature
5. 打开拉取请求。

📄 许可证

本项目采用 Apache 2.0 许可证 - 详情请参阅 LICENSE 文件。

🙋‍♂️ 支持

• 文档：GitHub README
• 问题反馈：GitHub Issues
• npm 包：@ashwinighuge/jenkins-mcp-server

🏗️ 架构

本项目基于以下技术构建：

• Python 3.12+ - 核心服务器实现
• FastMCP - MCP 协议处理
• Node.js - 跨平台包装器和进程管理
• Pydantic - 数据验证和序列化
• Requests - 具备重试逻辑的 HTTP 客户端
• CacheTools - 多级性能缓存