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 - 多級性能緩存