Jenkins MCP 服务器

一个企业级的 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 保护、双因素认证支持和安全身份验证
• 🌐 跨平台：适用于 Windows、macOS 和 Linux
• 🔄 重试逻辑：内置指数退避以提高可靠性
• 📡 传输灵活性：支持 STDIO 和 HTTP 传输
• ✅ 输入验证：基于 Pydantic 的健壮验证和错误处理

📋 先决条件

• Node.js：14.0.0 或更高版本
• Python：3.12 或更高版本
• Jenkins：2.401+（推荐）
• Jenkins API Token：用于身份验证

🛠 安装方法

方法 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 Token

1. 登录到你的 Jenkins 实例
2. 点击用户名 → 配置
3. 滚动到 API Token 部分
4. 点击 添加新令牌
5. 给它命名并点击 生成
6. 复制生成的令牌（安全保存！）

🚀 使用

命令行界面

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

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

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

# 显示帮助
jenkins-mcp --help

传输模式

模式	使用场景	命令
STDIO	Claude Desktop，直接 MCP 客户端	jenkins-mcp
HTTP	MCP Gateway，Web 集成	jenkins-mcp --transport streamable-http

高级用法示例

# 使用 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 Pipeline 作业构建的详细阶段状态。
• 参数：
  • job_name (字符串)：Jenkins Pipeline 作业的名称。
  • 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

• 描述：（演示）使用预配置的 LLM 提示总结构建日志。
• 参数：
  • job_name (字符串)：Jenkins 作业的名称。
  • build_number (整数)：构建编号。
• 返回值：占位符摘要和将使用的提示。

💡 使用示例

与 Claude Desktop

一旦在 claude_desktop_config.json 中配置好，你可以向 Claude 发出以下请求：

"列出所有 Jenkins 作业"

"触发 deploy-prod 作业，参数 version 为 1.2.3"

"显示 api-tests 作业构建 #45 的控制台日志"

"过去 24 小时内失败的所有作业的状态是什么？"

与 MCP Gateway

# 在 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